Doc TOC becomes invisible during scroll down

[adrian_nye@…]

Most of the Doc pages are much longer than the TOC, and when you scroll down to view the rest of the doc page the TOC disappears and you have a blank dark green column on the right side wasting 1/3 of the screen. Some pages are so long and it is tedious to have to scroll all the way back up to navigate anywhere else.

There are several solutions for this. One simple one is to do it like the following example page, keep the TOC always visible:
​http://msdn.microsoft.com/en-us/library/dd567845(VS.85).aspx
(when Microsoft does something better than Django it means Django really needs
to fix it!)

A second option would be to eliminate the right column and have a floating button that opens a TOC popup.
Then the doc could use the whole screen width.

[Malcolm Tredinnick]

It's far from clear that a floating TOC (or frames, as in the MS exmaple) is an improvement, since movement like that on a screen is very distracting from the reading flow. Don't know about you, but my keyboard has this handy "Home" button that immediately goes back to the top of the page, removing any need to scroll back there.

Whilst I think there's legitimate grounds for opinions to vary here, I'd be -1 on any change like this. The use-case to go back and forth to the TOC on a single page is a limited case. Some problems can be solved with docs reorgs (so that the need to go back and forth.

[adrian_nye@…]

Perhaps I should have mentioned another point. The TOC has links to sections of the current page, which are very useful
especially in the reference documentation. When they are visible. This is a common use case.

Secondly there is no movement in the MS example. You could argue against using frames but it is clearly more usable
that what we have now.

Apart from the question of how to accomplish it, isn't it clear that a column with the TOC in it is better than a blank column?

[Karen Tracey]

Replying to adrian_nye@yahoo.com:

Apart from the question of how to accomplish it, isn't it clear that a column with the TOC in it is better than a blank column?

Eh, not necessarily, and how to accomplish it is significant. Like Malcolm, I find floating things that move along as I scroll very distracting. And I don't find the frames solution much better -- I like there to be only one scroll bar for the page. That may be a personal quirk, but there you are: personally I prefer what we have now than either of the solutions mentioned so far. The top of the page is easy enough to get to if I want to see the TOC, as is simply searching on the page for a likely keyword to get where I really want to be.

[adrian_nye@…]

There's also the option to do it like O'Reilly Safari. Most doc browsers do have visible navigation/position indication.

But I guess people just don't like the idea so I'll
drop it. Thanks for considering it.

[Gabriel Hurley]

While I do agree that having the TOC readily at hand would be a minor improvement in convenience, I would have to agree with Karen and Malcolm in saying that it would also be somewhat distracting. I'm also strongly opposed to frames from a web design standpoint, and can't think of a javascript or css-based alternative I like better. Particularly for pages where the TOC is longer than the height of the browser window.

In the face of the reporter having already resigned the idea, no solutions people are in favor of, and no activity in 1.5 years, I'm gonna close this one as wontfix.

Thank you for the thought, though, adrian_nye! If you feel a better option has presented itself in the last two years, feel free to bring it up on the Django Developers list or IRC.

[adrian_nye]

After using this doc daily for years now, I just find it slow getting to the search box. Right now the order of the TOC column is Contents, Search, Browse.
On most doc pages, the search box is not visible if you hit
the HOME button - because it's at the bottom of the Contents which if often longer than the browser window.

How about changing the order to Search, Contents, Browse? Moving the search box to the top of the TOC column?
That way there is one click access to it.