http://www.alexkrupp.com/Jinja%20docs.html
FreeMind .mm file: http://www.alexkrupp.com/Jinja%20docs.mm
Ideally the HTML of the Python docs should be structured in such a way that the all the built-in functions, string functions, regex functions, etc. can be dumped into a mindmap automatically each time the documentation is changed.
Since HTML5 provides several new tags to help define the outline of a page and specify suitable headings to go with it, I’d probably look there first. The existing content looks fairly well structured, so hopefully it could be migrated with reasonable effort as a starting point, and any new/reorganised material to fit whatever new IA results from this exercise could then take full advantage. As HTML5 becomes more widespread, I suspect we’ll see both search engines and browsers take advantage of these outlines, just as search engines today have started to recognise site maps and present some results accordingly, so I think it makes sense to follow the presumptive standards unless there’s an obvious reason not to.
Given a clear outline one way or another, you could also do a lot to improve on the narrow, statically positioned tree on the left of each documentation page. That sort of navigation was probably sensible with the browsers and screen resolutions of the time when the current design was put together. Today, it wouldn’t be rocket science to use a wider nav area to take advantage of widescreen displays, and to have it fixed so it doesn’t disappear as you scroll down the page. You could provide some combination of top-level site navigation and navigating a possibly collapsible outline of the current page. However, perhaps you could also provide tools like navigating through search results as a separate list of excerpts like a SERP and/or by making the outline smart about say expanding and highlighting relevant sections when you first open the page. You could probably even do things like providing quick context-sensitive help for main page content, just as we use various interactive features to explore our code in editors/IDEs without leaving our current context.
This sounds like a fun project to work on. I’m almost sad that I don’t have a spare team and a half-year of free time to have a go! I certainly wish the organisers luck and hope a good development team lands the job.
I prefer a single page for random than having 20 something pages for random.x. Here is the doc for random.choice:
random.choice(seq)
Return a random element from the non-empty sequence seq. If seq is empty, raises IndexError.
A separate page for this will be textbook definition of overkill.If you already know what you are looking for(random.choice), a better way to lookup the docs is to either use the repl(help(random.choice)) or configure your editor to lookup the documentation. Python library docs is mostly contained in the docstrings.
It is not overkill as I see it, a page for random.choice with official documentation and annotations and comments would be good in my book.
Another solution could be to keep the pages as they are today but the possibility to click down the hierarchy to get to a more in-depth function-page where you can get comments, solutions, examples etc. This would cater for both tastes of documentation consumption. This would also solve the problem with coming into the docs from search, making it easier to get a 100%-hit directly when searching for a specific function.
Today when you search for 'random.choice python' you get to the random front page with 20+ random functions forcing you to first click on the google search result (probably with a lower CTR than if you have had the function name in the title) and then when entering the docs page hit CTRL+F and do a page search for 'random.choice'. That would make my life easier, and annotated documentation, preferably with some kind of "like"-functionality pushing the good answers up. I do get however that some people like to have the full spec for all random functions in one page...