Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Online documentation structure

Last updated on
8 August 2023

This section of the Online documentation guidelines provides guidance for organizing the structure of online documentation pages. This includes topics such as hierarchical organization, editing existing vs. adding new pages, separation of documentation for different Drupal versions, page length, author block, and page weight.

In contrast, the Online documentation style guide offers guidelines for the internal page structure, formatting, and markup, as well as for language usage, such as italicizing, bolding, spelling, and capitalization.

A note about the documentation scope

New pages are always welcome, but please note that the scope of the Drupal handbooks is limited to the installation, management, use and development of Drupal along with the integration of Drupal with other software and services.

General information about web development, products, tools, software languages, standards, practices, techniques, etc is considered out of scope unless the topic provides additional information which is specific to the Drupal environment. For example, a general tutorial on using CSS would be out of scope, whereas a discussion of how to work with CSS within a Drupal theme would be very much in scope. A procedure for installing Eclipse would be out of scope, whereas a procedure for configuring Eclipse for Drupal development work would be in scope.

Content that is beyond this scope may be removed.

Contents of this page


Modular structure
The Drupal documentation is migrating to a modular information architecture, loosely based on the DITA standard. There are three main topic types:

  • Concept Explanations, guidelines, overviews, etc.
  • Task A series of steps to accomplish a task.
  • Reference Detailed, factual information. For example, system requirements, a list of error messages, etc.

Rather than lengthy articles that try to cover a number of concepts and tasks, information should be broken down into the smallest units that can stand alone. In other words, a single node should only address a single topic (task, concept or reference item). Do not mix tasks with conceptual information.


Hierarchical organization:

  • Avoid unnecessary layers; they make documentation hard to find and hard to follow. For example, consider that in a book, the appendices are on the same level as "chapters" of the book.
  • Do not use hierarchical structure to create a sequence. Since handbook maintainers do not have access to the weight function, submit an issue asking that pages be placed in a certain order. This is a straightforward operation that will generally be performed promptly.
  • Container pages should have at least three child pages and each page must have a minimum length of 500 words. If a parent has only one child merge the child into the parent. If the overview information is substantial, move the bulk of the overview to a new child page called "About [topic]" and reduce the parent to a few sentences that very briefly introduces the topic. This also provides the important benefit of having the menu of child pages prominently displayed near the top of the parent (rather than hidden at the end of a lengthy introduction or overview).
  • Avoid duplication; it is better to link to existing documentation about a topic, rather than duplicate it (or nearly duplicate it) in a second location.
  • Ensure the parent page is organizationally named. Remember that a user starting at the top sees only one layer of titles at a time. Would someone looking for the topic on your page naturally select its parent from those available? If not, submit an issue report against the parent page's title.
  • Test the structure: Start at the top, and select a path that would lead a new user to your topic. If there is an absence of a clear path, or multiple plausible paths, submit an issue.
  • Consider forum requests: If the documentation page exists, but a forum inquiry indicates it couldn't be found, consider whether the documentation handbook structure is unclear for a new user looking for the topic. Rather than just providing a link to the page, provide the path to the page as well.
  • Hierarchy example:

    Bad:

    Main topic
--Theory
--Implementation
--Examples
----Example one
----Example two
--Special circumstances
----Case one
----Case two

    Good:

    Main topic
--Theory
--Implementation
--Example one
--Example two
--Special circumstance considerations
--Circumstance one
--Circumstance two

    In this example, the "Special circumstances" page in the top structure covered general considerations and was more than an organizational place holder, so a "Special circumstance considerations" page was placed ahead of the special circumstance cases in the bottom structure.

Back to top

Titles: In addition to the Style guide directions, also consider how the title of a page fits in to the overall structure. Is there a long flat list of titles, many of which "almost, but not quite" match a user's question?

Main chapters: A section of the online documentation or "guide" should generally have twelve subsections or fewer. More than twelve subsections probably indicates that there is a structural problem with the section.

Editing versus adding pages: Try to edit current pages rather than create new pages. It is better to cover a topic in one location succinctly, and then reference the topic from related pages. Editing existing pages rather than creating new ones also preserves links that reference current pages.

Versions: There is currently a single version of the online documentation and many pages apply to all versions of Drupal. The rationale for having only one unified version of the documentation at present is:

  • There are insufficient resources to maintain different sets of documentation for different versions of Drupal (we hope in the future be able to support versioning of the documentation).
  • Inconsistencies would develop between parallel versions due to only one book being corrected when the problem affects both.
  • Guidance on the version with documentation available is often useful to the reader who has a different version.

Information for different Drupal versions can be kept together on one page or separated on different pages. It is generally preferred to cover information for all the versions on a single page, but if instructions for the different Drupal versions differ substantially, separate pages are appropriate. Use the "Drupal version" drop-down menu and select which version(s) the page applies to.

If each version is dealt with on a separate page:

  • Organize the pages on the same hierarchical level.
  • Include the version number at the end of the title, so that one page is titled "Example topic for. 5.x" and the next is "Example topic for 4.7".

If multiple versions are dealt with on one page:

  • Select all the versions which the page applies to in the "Drupal version" drop-down menu.
  • Information on the page should be listed from newest to oldest version.
  • Mark the sub-sections for each version very clearly.
  • If there are no separate subsections for the different versions because the entire page applies to all versions selected in the "Drupal version" drop-down menu, state so early in the page, so that readers don't wonder which sub-sections apply to their version.

Page length: Longer pages of several screens are acceptable. Use <h2> or <h3> tags to provide sub-topic headings within the page. Very long pages should list the page contents (preferably with anchor links) after the opening paragraph.

Authorship: Avoid changing page authorship unless you have done a major re-write. It is not typical to change the authorship at all, and is not necessary to update it. (Currently, only site maintainers have access to the author field.)

Log message: Enter a brief log message to explain the page update.

URL path settings: For important high level pages, or for the main landing page for a module's or theme's documentation, you may want to create a URL alias (only site administrators have the ability to do this.)

URL aliases should be structured according to what guide they are in and whether they are for a module's or theme's main landing page.

  • Modules: http://drupal.org/documentation/modules/[project-name] eg. for Pathauto module, the project page is http://drupal.org/project/pathauto and the documentation landing page is http://drupal.org/documentation/modules/pathauto (the last part of the URL for the project page and the documentation landing page should be identical (and incidentally match the module's help page URL inside a Drupal site, if it has one -- in Drupal 7 this would be http://example.com/admin/help/pathauto.
  • Themes: http://drupal.org/documentation/themes/[project-name] eg. for the Bartik theme, the project page is http://drupal.org/project/bartik and the documentation landing page will be aliased to http://drupal.org/documentation/themes/bartik (the last part of the URL for the project page and the documentation landing page should be identical (and incidentally match the core theme settings page's URL, which in Drupal 7 would be http://example.com/admin/appearance/settings/bartik).
  • Other high level pages: Generally other high level pages should use sensible aliases that denote which guide they are in. Not all pages need to be aliased, nor should they, as it increases the site's load. Only important or frequently referenced pages should be aliased. Examples of the structure:

Weight: Only site administrators can change the order of pages that appear under a common heading. To request such changes, submit an issue report.

Outdated/deprecated pages: If you encounter a page that is entirely about unsupported versions or is otherwise outdated:

  1. Tag it as Deprecated if it isn't already.
  2. Edit the title so it starts with "ARCHIVE:"
  3. Move the page to the book Archive (by selecting "Archive" from the Parent drop-down menu).
  4. Unpublish the node. Only admins have permission to do that, so if you don't have permission, just leave it published.

There are a few exceptions. The following handbook sections will continue to hold information about old versions:

Pages that have information about both old and new versions can be edited to describe only current versions. (The outdated information will still be available via the "Revisions" tab.)

See also Obsolete and Duplicated Documentation Pages.

Back to top

Drupal.org Documentation Taxonomy

Drupal.org documentation is organized by three different vocabularies. You are encouraged to classify your content using these vocabularies to better help people find documentation that is relevant to their skill level, interests, and needs. (See the Taxonomy documentation for more on taxonomies, vocabularies and terms.)

Note: these vocabularies can only be applied to documentation that is entered as Book content.

Audience

Documentation can be targeted to different audience types. Content that is relevant to multiple audience types can be assigned multiple terms in the Audience type vocabulary when necessary. Many people will play more than one of these roles in the course of their work with Drupal. These audience types are by no means meant to imply exclusivity.

  • Designers: people who are doing graphic design work for Drupal websites. Designers do not necessarily create or modify themes, but rather do the graphic work that is converted into a theme by a themer.
  • Developers and coders: people who create and develop modules, code Drupal functionality, and work on Drupal core, core modules or contrib modules.
  • Documentation contributors: people who write, edit, or otherwise contribute to Drupal documentation, both on Drupal.org itself and elsewhere.
  • Site administrators: people who install and configure Drupal sites or handle administrative and configuration tasks for existing sites.
  • Site users: people who use and create content on existing Drupal sites.
  • Themers: people who theme Drupal sites, nodes, content types, module functions, etc.

Drupal version

Content that is specific to certain Drupal versions are assigned terms from the Drupal version vocabulary. When writing documentation, choose the Drupal version(s) that best apply to your post.

Page status

Help with the Drupal documentation efforts by indicating the most appropriate status for the page: No known problems, Incomplete, Insecure code, Needs copy/style review, Needs dividing, Needs technical review, Needs updating, or Deprecated.

Please help by indicating the most appropriate status of this page.

Back to top

Help improve this page

Page status: No known problems

You can: