[Twisted-Python] Task-based documentation started

[Albert Brandl]

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.

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.

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.

The "Everything Else" section should not contain links that are already 
presented somewhere else. 

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?

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.

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