Documentation writer's guide

This Documentation writer's guide covers overall considerations for the handbook which should be kept in mind when editing and adding 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.

The purpose of these guidelines is to make the handbooks more consistent and usable, particularly the navigation. These guidelines, though written mainly for documentation maintainers, will also be useful for all documentation contributors, who submit issues and can add pages.

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

See Handbooks overview for a description of the five handbooks: "About Drupal," "Installation and configuration," "Customizing and theming," "Developing for Drupal," and "About Drupal documentation."

See the End user guide for help with adding pages or editing pages. All drupal.org users can now create new pages in the handbooks. But when someone else updates a page you created, Drupal tracks that person as the page's author, and you lose ability to edit it. To update it, submit an issue, or request to join the documentation team, which will give you permission to edit most handbook pages.

Hierarchical organization:

• Avoid unnecessary layers; they make documentation hard to find and hard to follow. Consider for example how in a book, the appendices are on the same level as "chapters" of the book.
• Do not use hierarchical structure to achieve the desired sequence. Since handbook maintainers do not have access to the weight function, submit an issue; this is a straightforward operation that will generally be performed promptly.
• Avoid nearly-empty "container" pages.
• Introductory material should normally be in the parent page, not a first child page, in a large multi-page topic.
• Short child pages covering a particular variation should be incorporated into the parent page if practical. This is particularly true for single child pages.
• 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 where it may be applicable.
• 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 the path a new user would if looking for 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.

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: The five handbooks should generally each have twelve chapters or fewer, since the "Handbooks" tab shows all the top-level chapters of all of the books.

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 <b> or <strong> 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: Pages which are completely about unsupported versions or are otherwise outdated: Edit the title so it starts with "OUTDATED:", move it to the book Archive.
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 which 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.)