Scot, you've summarized what I've run into as well beautifully. My problem has never been with the documentation once I find it - it has been the path to finding it. Another frustration is trying to find a part of the documentation I know I've seen before a second time. I seem to go round and round in link circles for a frustrating amount of time. Taxonomy here is important, because of the frequent use and reuse of potential search terms throughout the documentation.
Regards, Tim On Monday, January 4, 2016 at 2:45:56 AM UTC-5, Scot Hacker wrote: > > 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/b0f50682-2c4b-42f8-a4b9-33fc3121f315%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
