Handbook structure

This section of the Handbook Style Guide provides guidance for organizing the structure of handbook 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 Handbook style offers guidelines for the internal page structure, for formatting, and markup, as well as for language usage, such as italicizing, bolding, spelling, and capitalization.

Contents

• Hierarchical organization
• Titles
• Main chapters
• Editing vs adding pages
• Versions
• Page length
• Authorship
• Log message
• Weight
• Outdated pages
• Documentation taxonomy
  • Audience type
  • Drupal version
  • Page status

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 two child pages. 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 handbook should generally have twelve chapters or fewer. More than twelve chapters probably indicates that there is a structural problem with the handbook.

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 only one set of documentation handbooks, since many pages apply to all versions of Drupal; since there are insufficient resources to maintain different sets of handbooks for different versions of Drupal; since inconsistencies would develop between parallel versions due to only one book being corrected when the problem affects both; and since guidance on the only available version 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, v. 5.x" and the next is "Example topic, v. 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 links) after the opening paragraph.

Authorship: Avoid changing page authorship unless you have done a major re-write. (Currently, only site maintainers have access to the author field.)

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

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 pages: If you encounter a page that is entirely about unsupported versions or is otherwise outdated, edit the title so it starts with "OUTDATED:" and then move the page to the book Archive (by selecting "Archive" from the Parent drop-down menu). There are a few exceptions. The following handbook sections will continue to hold information about old versions:

• http://drupal.org/upgrade
• http://drupal.org/update/modules
• http://drupal.org/update/theme

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.)

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 type

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 updating, or Deprecated.

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

Back to top