[Twisted-Python] prerelease preview predocumentation

Glyph Lefkowitz glyph at twistedmatrix.com
Wed Mar 30 13:38:55 EDT 2011


On Mar 29, 2011, at 3:10 AM, Albert Brandl wrote:

> On Mon, Mar 28, 2011 at 09:27:04AM -0400, Tom Davis wrote:
>> 
>> It's great to have everything indexed on one page with easy drill-down 
>> into specific sections. It becomes really obvious where the hierarchy 
>> can be optimized and how we can logically go about breaking up the 
>> various sections.
> 
> This is right. But I was confused by the fact that the first-level items 
> in the list ("Twisted Conch Documentation", "Twisted Core Documentation", 
> etc.) link to pages that _again_ present links to the second-level items.
> Adding to my confusion was the fact that the links on the main page have
> different names from the ones on the subpages.

You're absolutely right.  The organization is a total mess.  But here's the surprise: the organization is not new :).  This is the exact same organization that the documentation has had for years.  The difference is that you can see it now, and notice that it's a problem, rather than just search for a document that you want, find that one document outside of the navigation structure, and ignore the rest of the docs (which is what most people do now).  I think that's a very good thing.

For example: both <http://twistedmatrix.com/documents/10.2.0/> and <http://twistedmatrix.com/~glyph/sphinx-preview-11.0pre1/> have a "conch" link.  And as you can see when you follow that link, <http://twistedmatrix.com/documents/10.2.0/conch/> looks a lot like  <http://twistedmatrix.com/~glyph/sphinx-preview-11.0pre1/projects/conch/index.html>.

This issue will be probably be fixed after the migration.  That is, I would certainly be happy if it were fixed before, or at any time really, but fixing it probably requires some tweaks to release infrastructure that would better be put off until we've deleted most of that part of the release infrastructure.  The important point is that it should stop the migration from happening, since the results are actually better now than they were, just more noticeable.

At any rate: thanks for the feedback, it's appreciated!

-glyph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110330/6ec77bbd/attachment.htm 


More information about the Twisted-Python mailing list