Making our documentation more cohesive

[Brent Smith <gnome nextreality net>]

So, I've embarked on a mission to tidy up how some of our documentation
is listed in yelp.  My main goal here is consistency.

A wikified version of this email can be found at 
http://live.gnome.org/Yelp/ConsistentDocs

My first goal is to:

1) Verify that each help document is in a reasonable category

Yelp uses scrollkeeper categories to create the table of contents which
you see when yelp first opens.  Some modules in GNOME obviously are in
incorrect or unreasonable categories.  One such example is Zenity.  The
zenity/help/zenity.omf.in file lists its category as "GNOME|Desktop"
where a more appropriate category would be "GNOME|Utilities".

Because it is currently set as "GNOME|Desktop" it shows up along with
the Accessibility Guide, the User Guide, etc in the table of contents.
These obviously should not be categorized with Zenity.  By changing this
to "GNOME|Utilities", zenity will appear in the Accessories ->
Applications in the table of contents, which is much more reasonable
given the nature of the application.

(To see how scrollkeeper categories are converted into the table of
contents in yelp, see the yelp/data/scrollkeeper.xml file)

I've created a tracker bug against yelp (for lack of a better component)
here:  http://bugs.gnome.org/show_bug.cgi?id=318900

* I would ask that you would file other bugs as you see fit, and add
them as a dependency to this bug.  If you are unsure about a category,
please email gnome-doc-list so we can discuss the most appropriate
category.

Current scrollkeeper categories can be found here:
http://scrollkeeper.sourceforge.net/documentation/categories.html


My second goal is to:

2) Standardize the titles of each document by removing version numbers,
fixing capitalization, removing unnecessary articles and adding a type
to the title such as "Manual", "Tutorial", or "Guide".

- Many documents have a trailing version number in their title.  I would
  like to remove this from all documents, since docbook provides an
  element, <releaseinfo>, to contain this.  Having the version number in
  the title is superfluous and distracting.  This will need to be
  changed in translations as well.

-  As for capitalization, refer to the HIG guidelines at:

http://developer.gnome.org/projects/gup/hig/2.0/design-text-labels.html#layout-capitalization

  Basically, capitalize all words in the element, with the following
  _exceptions_:
    * Articles: a, an, the.
    * Conjunctions: and, but, for, not, so, yet ...
    * Prepositions of three or fewer letters: at, for, by, in, to ...

- Unnecessary articles include "The", "A", "My", etc.  Please do no use
  these in the document title.  One such example is " The Aisleriot
  Manual" which should simply be "Aisleriot Manual".

- Finally, your documentation should indicate the type of document in
  the title.

  * "Manual" - If the document describes usage information for an
               application, then include "Manual" at the end of
               the title. Please don't use "Help Manual" or
               "Reference Manual".
  * "Guide"  - If the document is user-centric and describes how
               to perform tasks related to a specific topic, then
               include "Guide" at the end of the title.  Examples,
               "Accessibility Guide", "System Administration Guide".
  * "Tutorial" - self explanatory

I've created a tracker bug against yelp (for lack of a better component)
here:  http://bugs.gnome.org/show_bug.cgi?id=318887

There is already one dependency for that bug which fixes all the above
issues mentioned with a patch, except for the translated docs.

* I would ask that you would file other bugs as you see fit, and add
them as a dependency to this bug.  If you are unsure about something
please send a message to this list.

One last remark: it would be nice if all documents included a
meaningful <abstract role="description"> element in the articleinfo or
bookinfo sections of the docbook file.  This text will be added below
the entry in the table of contents that yelp displays.  "User Manual
for &appname;" is _not_ a meaningful description.

--
Brent Smith <gnome nextreality net>
IRC: smitten