One thing that would really make the website work better is to make pages like http://docs.python.org/library/stdtypes.html hierarchical with an overview and one or two sub levels so each function gets its own page, making it easier to find via search (The Google) and do dynamic linking from IDE:s or whatever if the url routing were set up smart.
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...
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.
I created it manually using FreeMind. I basically just copied and pasted each section from the docs, and then grouped some of them together in logical ways to make it easier to read. I also deleted most of the usage notes about how previous versions worked, since I was starting with the newest so all of that was irrelevant to me.
> Today when you search for 'random.choice python' you get to the random front page with 20+ random
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.
If you’re concerned about locating information quickly via Google, maybe thinking of how sites like the Stack Overflow family work, then having many pages is one possible idea. However, I would worry that this is restricting the design purely to accommodate today’s search engines. Using many small pages would surely reduce the usefulness for users who prefer browsing to searching.
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.
Yes, it'd be nice if that search went straight to the function in question -- however, it'd make the docs a lot more broken up and IMHO harder to use if each module had 15 sub-pages for the individual functions. Harder to scan or Ctrl-F on the page, for one thing.
Often when I need to lookup something in the docs it is a specific function, I do not want scan large blocks of documentation for a whole module, internal linking to similar functionality and all other functions in the module reachable with one click would solve two problems for me: 1. Take away the information overload you get today when searching for specific documentation on one thing and 2. Make all the other things reachable in one click, CTRL+F + Click.
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...