[documentation] [Documentation feature] Update to Documentation writer's guide

Mon Jan 22 17:38:26 UTC 2007

Issue status update for 
http://drupal.org/node/110062
Post a follow up: 
http://drupal.org/project/comments/add/110062

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     feature requests
 Priority:     normal
 Assigned to:  karldied
 Reported by:  karldied
 Updated by:   karldied
-Status:       patch (code needs work)
+Status:       fixed

The documentation writer's guide is posted at
http://drupal.org/node/336. Thanks for the good feedback and comments. 

Summary of related issues:
http://drupal.org/node/105356 - Make documentation specific to drupal
version (open)
http://drupal.org/node/107721 - Allow documentation maintainers to more
easily copy nodes (open)
http://drupal.org/node/107953 - Authoring Guidelines for placing/
organising v4.x and v5 documentation (fixed)
http://drupal.org/node/110062 - Update to Documentation writer's guide
(fixed)

The new Documentation writer's guide is issued under #4. 

#3 was treated as a sub-section of #4. 

For #3, I also updated http://drupal.org/node/14279 - About Drupal
documentation, to discuss that handbook pages are marked for version
applicability.

karldied

Previous comments:
------------------------------------------------------------------------

Wed, 17 Jan 2007 04:03:00 +0000 : karldied

The current Documentation writer's guide [1] 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 [2]. 

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 [3], 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 [4] 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 [5] if you need help with adding pages [6] or
editing pages [7]. 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 [8], 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 [9], 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
[1] http://drupal.org//node/336
[2] http://drupal.org//node/23367
[3] http://drupal.org//node/22299
[4] http://drupal.org//node/23743
[5] http://drupal.org//node/6261
[6] http://drupal.org//node/337
[7] http://drupal.org//node/7890
[8] http://drupal.org//node/23367
[9] http://drupal.org//node/107005

------------------------------------------------------------------------

Wed, 17 Jan 2007 14:50:20 +0000 : CogRusty

I think we should also try to make the logic understood -- that the most
important thing about organization is that the user should be able to
find stuff, and that sometimes this can become difficult because of:

- Vagues higher level topic titles which don't make the user confident
to pick one and drill down,
- Long flat listings of titles many of which "almost, but not quite"
match the user's question.

A handbook editor is not always aware of the discussions about
organization. So, some general discouragement for adding parent pages is
good advise. For example:

- Never add vague parent page titles such as "Example" or
"Introduction", and generally avoid them in page titles as well.
- Suppose you came for the first time to the handbook and were looking
for your entry. Under which existing parent page would you expect to go
and find it? If there is no good existing parent page, then create one
where you think you would be looking for it *and* file an issue.
- If more than one existing parent pages seem reasonable for adding
your entry, and they seem to be used for entries similar to yours, then
place it where you think you would be looking for it *and* file an
issue.

------------------------------------------------------------------------

Thu, 18 Jan 2007 01:49:14 +0000 : karldied

Thank-you. I've incorporated your comments, adding a 'titles' section
(for organizational matters, not duplicating Style guide directions),
and re-organizing the 'Hierarchical organization' section into a list.
Also broke out 'purpose' better. Any more comments? 

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

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

See Handbooks overview [11] .... [as before]

*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 and 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.

--Short child pages covering a particular variation should be
incorporated it into the parent page if practical. This is particularly
true for single child pages. 

--Avoid duplication; it is better to link to exiting 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. 

--Example  [as before]

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?

[10] http://drupal.org//node/22299
[11] http://drupal.org//node/23743

------------------------------------------------------------------------

Fri, 19 Jan 2007 03:03:44 +0000 : karldied

O Govinda: Thanks for e-mail with suggestions, which I've incorporated
into the draft. 

The documentation issue at /node/107953 Authoring Guidelines for
placing/ organising v4.x and v5 documentation [12] is related to this
issue. I've put forth a proposed sub-section to the "Documentation
writer's guide" there.
[12] http://drupal.org//node/107953