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
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
