The written quality of the Django docs has been a selling point for years, but discoverability has never been great. I wanted to add two notes:
1) The front page of the docs says docs are organized into four sections (Tutorials, Topic Guides, Reference Guides, How-To Guides). And it's been proposed that we add a fifth docstring-generated API Reference as well. But remember that most people looking to solve a problem under deadline start with search, not taxonomy. Search results do *seem* to be labeled with the section of the docs they come from, but the sections referenced don't actually correspond to the four sections we say use! If I search for "forms" I get results that claim to come from "API Reference," "Using Django," "Release Notes," which don't match the names of our four sections. I propose that A) search results clearly indicate the doc sections that we claim we use for organization; B) Search results be grouped by type (e.g. show all results from Using Django first, followed by all results from API Reference)... or whatever. Or a user could use checkboxes to select which section of the docs they want to search. Or faceted search results so users can quickly toggle or filter the sources of the search results? There are a lot of ways to solve this - just pointing out that our search experiences could be sharper and more customizable. 2) I've encountered a number of situations where search didn't help because I didn't yet know enough to search for the right thing. I remember early in my Django experience trying to figure out how to have a "global variable" for my project and that search string not turning up what I needed to know... because what I really should have been searching for was "context processors".* I think we could make strides in search-ability through the indication of a tagging system. Tags could either be controlled through commits, or dynamic (users could tag topics on the fly, and a weighting system would apply to search results). * Even today, searching the docs for "context processor" does not take me quickly to a clean example of how to implement a context processor - I really have to dig for this information. ./s -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at https://groups.google.com/group/django-developers. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/da7ae84d-7696-4705-b8a3-115c9ec40b94%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
