TopicBasedHelp

Revision 6 as of 2006-11-10 19:04:18

Clear message

Summary

The help for most Gnome projects, and for Firefox, is written as a manual. This approach works poorly for people trying to find quick answers and read them from a computer screen. Some way needs to be found of splitting help into individual pages that automatically link to each other.

Rationale

See HelpfulHelp.

Use cases

Scope

A full implementation of topic-based help requires a new file format (DocBook inappropriately assumes books with chapters and sections), a license appropriate for individual help pages, indexing support from scrollkeeper/spoon, and support from the help viewer. This is not realistic for the Feisty cycle, because

  • upstream and we do not have sufficient resources to implement it ourselves.

This will most likely require an implementation of [http://www.gnome.org/~shaunm/quack/mallard.xml Project Mallard], which the GNOME Documentation team has been working on for the past year. But this is still vaporware. (See also [http://norman.walsh.name/2005/10/21/dita Dita].)

So for now we will restrict this to reorganizing the Desktop Guide in preparation for splitting it into individual help pages. We will also incorporate relevant documentation from the Official Ubuntu Book and from Ubuntu Forums.

Out of scope:

  • Integrating topics directly with the Upstream documentation. (This will have to wait until Project Mallard is implemented, otherwise there would be major and licensing problems.)

Once this new format is set in place, it will make it easier to draw in new documentation from other sources and place it within the topic-based documentation structure.

Design

  • Help pages should be kept as short as necessary to answer a question, describe how to perform a task, or explain a specific topic. (No more than about four or five paragraphs.)

  • The front page should arrange user goals by subject, possibly also with links to the most common specific issues (e.g. "Installing software").

Implementation

  1. Documentation team members should create and refine example pages using the desired structure.
  2. The rest of the Desktop Guide should be rearranged to follow the style set by the example pages.

  3. MatthewPaulThomas will work with the Gnome documentation team to specify the file format and markup language for Project Mallard in the next six months.

Outstanding issues