On Tue, Feb 1, 2011 at 3:44 AM, Albert Brandl <albert.brandl@weiermayer.com>wrote:
On Mon, Jan 31, 2011 at 02:41:38PM -0500, Tom Davis wrote:
Thoughts?
I think that the overview in the first two sections is very good. It made me curious to learn more.
The "breadcrumbs" on the main page look like this: "Contents :: Serving on the Web — HTML, CGI, WSGI, etc. » " Might be a problem with the Sphinx configuration.
Yeah, this is just how the Sphinx template lays things out and it's the default one I use for documentation on my site, merely because the color scheme is similar. It's definitely not the greatest and a Twisted-theme one already exists so we'll be working from that.
Not sure about the link "read more about Twisted": There _is_ more about Twisted on the rest of the page. When I clicked the link, I expected to be redirected to twistedmatrix.com or something like this. Maybe you don't need a link at this position at all.
Well, that was originally going to lead to some history/about stuff, but looking at it again that doesn't seem like an initially great use of time.
In the "Why Use Twisted" section, you write "Framework" - not sure if this should be uppercased. But there are some other nouns (Tasks, Project Documentation) that are written this way, so maybe it's Your Way Of Emphasizing Things ;-).
I'm also not sure if the explanation why I would use Twisted should be in bold letters. Everywhere else you use italics.
Do you intend to create a task description for connecting to an SSH server (maybe with certificates)? This is something that whould have been handy for me in the past.
Either create or expose one that already exists, yes.
The "Everything Else" section should not contain links that are already presented somewhere else.
These are ToC trees which are different from inline links. I don't feel there's much harm in linking to something twice on one page especially when the same words are used and one of the uses is clearly a ToC.
Do you intend to add some links to external pages here (e.g. the API documentation or other web pages describing how to use the framework)? Or should this documentation be self-contained?
API links will be common and will be under some reference/links area, I'm sure. It is very much a work in progress.
One small usability quirk: The presentation of links in an orange, bold font does not have much recognition value. I think it would be better to use the standard way of marking links by using a blue, underlined font. The same goes for links that have already been visited.
Again, this is a Sphinx template issue so we'll see how it changes with the actual Twisted one :) Thanks for the feedback! -Tom
Best regards,
Albert -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python