Python.org Redesign Request for Proposals

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.

Thank you - I don't disagree with you, honestly though, the overhead of trying to manage those separate entities will quickly outstrip the time and ability the volunteers who are evaluating and managing this process have.

If a given company feels it is lacking in any single area, I encourage them to include other specialists in that area as part of their bid - for example, if they're awesome back end designers, but can not do front-end design, I would expect them to find a trusted designer to work with them as part of the bid.

Even though this effort is funded, the management of it, the evaluation of the designs/etc is all volunteer based. We can not chase multiple contractors :(

That said, the design people/firms I spoke to about this seemed to understand this and stated they would do as I outlined above.

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.

I like it! How did you create the jinja html? Did you first create the .mm and then export to html somehow? Or did you have to create it manually?

In something as complicated and as has as much information as a an open source project does, the need for a clean, organized, thoughtful interface plan/design is paramount. The quicker the information is to find and the more digestible it is, the quicker the project will be adopted and built upon... in theory of course!