Opened 16 years ago

Closed 14 years ago

#10093 closed (wontfix)

Table of Contents should show two levels

Reported by: adrian_nye Owned by: nobody
Component: Documentation Version: 1.0
Severity: Keywords: Table of contents
Cc: Triage Stage: Design decision needed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Currently the TOC shows only top level headings. For example if you want the doc on QuerySets you have to know to click on "Models and Databases" and then you see "Making Queries". The word "Query" does not appear anywhere at the top level. It's unclear that some of the top level topics are single files, while others include a whole list of files.

A two level deep TOC would be better (and it is the standard in technical books). This has several advantages: first it is quicker to get to what you need. Second you can see how the doc is organized in one view. Third you see more key topics and it is easier to understand the scope of the top level terms.

Change History (2)

comment:1 by Tim Graham, 16 years ago

Triage Stage: Unreviewed → Design decision needed

comment:2 by Gabriel Hurley, 14 years ago

Resolution: → wontfix
Status: new → closed

For the sake of comparison I just tried building the docs with the TOC :maxdepth: value increased to show the added level.

Quite honestly, it made the page excessively long (nearly 10 printed pages) and made it much harder to actually find what you were looking for without doing a find command on the page.

It also ruined what I consider to be one of the best features of the TOC: it shows you the organization of the docs at a glance.

While it may be the standard for printed technical manuals, I feel this change would be detrimental to the overall usability of the TOC page.

Thank you for the suggestion, though. It was an interesting experiment. I'm sorry no one dealt with this previously!

Note: See TracTickets for help on using tickets.
Back to Top