Update to Documentation writer's guide

The current Documentation writer's guide is a one-paragraph two-sentence page:

Drupal documentation for the Drupal handbooks and the admin/help within each Drupal installation is collaboratively maintained on drupal.org by the documentation team. Documentation team members additionally coordinate the creation of marketing materials, the Drupal Newsletter, and other document efforts relevant to the Drupal community.

This information now rests in the opening paragraph of Joining the documentation team.

The following content is proposed to update this page:

T: Documentataion writer's guide

This page covers overall considerations in editing and adding handbook pages, including 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 improve handbook navigation consistency and usability. Although it concerns primarily to documentation maintainers, it also applies to all documentation contributors, since they submit issues and can add pages.

You should also be familiar with the style guide, which covers 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 if you need help with adding pages or editing pages. All drupal.org users can now create new pages in the handbooks. However, when a page is updated, the latest author is tracked; you will lose ability to edit it. You can submit an issue for an update, or request to join the documentation team, which will give you permission to edit most handbook pages. Previously, new pages went into a moderation queue prior to publication, where they were rejected, remanded for further revision, or approved and published.

Guidelines when editing and adding pages

Hierarchical organization: Avoid creating unnecessary layers; they make documentation harder to find and harder to follow. For example, think of appendices as on the same level as other "chapters" of the topic.

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.

Sometimes the temptation to use excess hierarchical structure is to achieve the desired order, since handbook maintainers do not have access to the weight function. Instead, submit and issue; this is a straightforward operation that will generally be performed promptly.

If there is a short child page covering something like "Considerations for Windows XP," incorporate it into the parent page if practical. This is particularly true for single child pages.

Main chapters: The five handbooks should have a limited number of chapters, perhaps around 12, since the Handbooks tab presents all the top-level chapters of all of the books.

Adding versus editing pages: The preference is to edit existing pages, rather than create new pages. It is better to cover a topic in one location and do so succinctly, and then reference the topic from other related pages. Also, many handbook pages are referenced, so editing them instead of replacing them keeps links intact.

Version separation: The preference is generally to have one page that covers all versions, rather than placing the older version information in a child page. If there are substantial differences between versions, separate pages are appropriate. The reason for keeping the information together is that segregated version pages produce maintenance problems. When an issue is updated on one version page, the other version pages are often neglected.

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 contents (preferably with links) after the opening paragraph.

Authorship: Avoid changing page authorship unless you have done a major re-write.

Log message: Enter a brief log message to provide anyone reviewing the page revisions an idea of your changes.

Weight: Adjusting the order of pages under a common heading requires site administrator role. Submit an issue report to request such changes.

- - - - - - - - - - - - - - - - - - - - - - - - -
Feedback sought. This is part of issue Improvements for Handbook - how to contribute, but big enough to separate out. I also have a page in draft to improve issue submissions for the doc project, based on my lessons-learned joining the team. -karldied