Restructure the Site Building Guide

The Site Building Guide is a sprawling beast that really cries out for some serious rethinking. Right now it covers about 3,500 topics and a staggering 6,000 pages. That's at least three times larger than the next largest guide. But even though the guide is huge, there are actually about 6,000 modules for Drupal 7 which suggests that the guide (at only 3,500 topics) might actually be missing an enormous amount of potential content.

The problem is not the size of the guide per se, it's the structure and the findability/navigability of the content. The other guides, by contrast, seem relatively coherent. When I scan down the top level headings of those guides, I can mostly understand what I'm going to find in each section and the order seems fairly logical.

The Site Building Guide, in contrast, tries to cover nearly everything you can possibly do with every Drupal module (except the relatively small handful of modules that are specific to the other guides). This results in at least four problem areas:

• There are sections of the Site Building Guide that have freakishly long lists of topics covering an absurdly diverse range of topics with no structure whatsoever like http://drupal.org/documentation/modules/contributions, http://drupal.org/documentation/customization/howto and http://drupal.org/documentation/site-recipes.
• There is a more structured approach in this section http://drupal.org/node/1241116 which is perhaps easier to navigate but requires a lot of drilling up and down layers.
• Huge potential overlap between all of the above.
• Confusion among documentation contributors about where to place their content.

Now that we're getting a little closer to having new tools that will help manage the structure of the Drupal docs, I've been analyzing the guides to understand what should or could change in the brave new paradigm where we have the ability to:

• Map a single topic to multiple structures
• Display content filtered by version

Most of the guides will probably not change all that much, except that they should be noticeably slimmer and easier to navigate, since the reader won't be presented with a jumble of content from two or three different versions of Drupal.

But something desperately needs to change with the Site Building Guide. I suspect that the solution will involve a combination of the following:

• Tagging content using the categories that are currently used in the module section of Drupal.org.
• Views (with exposed filters)
• Content maps