[Twisted-Python] prerelease preview predocumentation

Kevin Horn kevin.horn at gmail.com
Wed Mar 30 14:09:55 EDT 2011


On Wed, Mar 30, 2011 at 12:38 PM, Glyph Lefkowitz
<glyph at twistedmatrix.com>wrote:

>
> 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
>
>
Er, you mean it should _not_ stop the migration from happening?

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110330/46016539/attachment.htm 


More information about the Twisted-Python mailing list