Created by: gwideman, Feb 25, 2012 11:32 pm
Revised by: gwideman, Mar 17, 2012 11:52 pm (22 revisions)

[Work in progress]


I have recently (Feb/March 2012) been conducting a study of Drupal's documentation. I undertook this task for several reasons:
  • Understanding Drupal: I wanted to understand more about Drupal, and it seemed to me that's own docs ought to be part of that endeavor, yet were not as accessible as one might have wished. Why? What might I do to prevail in penetrating them?
  • Drupal as a document platform: One of my interests in Drupal is as a platform in which to develop and publish documentation. The Drupal docs themselves perhaps provide an ongoing example in this area of what works and what doesn't.
  • Drupal as collaboration environment for a community: The Drupal docs process is an example of a community of folks working together to produce something collaboratively -- in this case documentation, but also the Drupal product itself (and its many associated components). What might there be to learn about how the platform's features do or don't foster collaboration and quality results?
Documentation tree
As a start, I have set out with the following objectives in mind:
  • Characterize the structure and extent of the documentation
  • Display the conceptual landscape which the documentation covers
  • Try out some statistics to help quantify salient characteristics of the body of documentation
  • Identify and quantify aspects which make the documentation difficult to penetrate and use, or, to put it more positively, to identify key approaches to making it more usable.


At the moment, the study is organized as follows:
  • Statistics_about drupal,org's docs. How much is there, and what characteristics does it have, such as age, use of images, intensity of comments, and so on.
  • Collapsible tree views of (substantially) all pages:_Browsing these trees is enormously informative. What I've implemented so far is primarily a proof of concept to:
    • Provide me some immediate way to wrap my mind around the body of docs. (For that, it works!)
    • Assess whether such a large tree works smoothly in typical web browsers (Simple version: surprisingly snappy!)
      • ...and assess whether performance is still acceptable when loaded up with more functionality than it has at the moment.
    • Assess what other info about the docs or the hierarchy can be usefully exposed and/or bubbled up the tree.
      • Example: Count of how many pages lie below this node -- very useful when browsing.
      • Assess how to display info so that it's useful, but not visually distracting
        • A Tree Grid is probably an important next step
        • Switch details on/off
        • Use color or other indicator to display anomalies or other points-of-interest, such as comment activity.
    • Understand what use cases this tree might be useful for:
      • Users acquiring an overview of the documentation's conceptual landscape, and browsing for clusters of docs on a particular topic.
      • Doc maintainers assessing and revising the structure of the documentation hierarchy
  • Issues and challenges with the Drupal book's navigation_concept and implementation
    • This page discusses the requirements for a "Table of Contents", and how they are only partially satisfied by the navigation features of Drupal's book module.

Related discussions

Links to related discussions on d.o, and maybe elsewhere.
Kind of thing
Article, issue etc
Create date
Last edit/comment date


Trees (but no D7 activity it seems)

Want the ability to create multiple outlines/maps

Cmty doc page (GIG)
Help and Official Documentation System
Lengthy and detailed requirements/spec.

Groups Doc Team
Towards Docs Sustainability

Develop a plan to make it more clear that the current Documentation on is community maintained.

Discussions for additional improvement ideas should happen on this follow-up issue: #1287784: Follow-ups to improve the community docs

Discussion regarding the redesign of the navigation portion of the page has been moved to this issue:#1289090: New navigation for d.o community docs

Discussion of a new "curated" docs area that is more tightly controlled is being discussed on:#1291058: Make a curated docs section

Groups Doc Team
Documentation and Docs Team Proposed Restructuring

Cmty doc page (GIG)
Documentation Team and Leader Responsibilities
same Allow inline images to be posted to d.o project pages, doc pages and comments without special permissions.

/node/1287784|#1287784/ Follow-ups to improve the community docs
Discussion regarding the redesign of the navigation portion of the page has been moved to this issue:
/node/1289090|#1289090/ New navigation for d.o community docs
Discussion of a new "curated" docs area that is more tightly controlled is being discussed on:
/node/1291058|#1291058/ Make a curated docs section
And in the Remaining Tasks section below, there are a few follow-up issues for specific ideas.