TopicBasedHelp

Differences between revisions 6 and 7
⇤ ← Revision 6 as of 2006-11-10 19:04:18 →
Size: 2691
Editor: 207
Comment: BoF with AndreasLloyd
← Revision 7 as of 2006-11-10 19:21:57 → ⇥
Size: 2760
Editor: 207
Comment: UbuntuHelp/PageStructure, and other notes
Deletions are marked like this. Additions are marked like this.
Line 8: Line 8:
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. To make Ubuntu's help more useful, we should rearrange the Ubuntu Desktop Guide so that each page is short and answers a specific question or explains a specific topic. We should also work with the Gnome documentation team to implement a useful front page for the help viewer, and to accelerate the development of their Project Mallard.
Line 12: Line 12:
''See'' HelpfulHelp. 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.
Line 14: Line 14:
== Use cases == ''For more detail, see'' HelpfulHelp.
Line 18: Line 18:
A full implementation of topic-based help requires a new file format (Doc``Book 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.		 A full implementation of topic-based help requires a new file format (Doc``Book 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 it is not implemented upstream and we do not have sufficient resources to implement it ourselves. Upstream plans to implement it as [http://www.gnome.org/~shaunm/quack/mallard.xml Project Mallard], which the GNOME Documentation team has been working on for the past year, but so far this is vaporware. (''See also'' [http://norman.walsh.name/2005/10/21/dita Dita].)
Line 21: Line 20:
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.		 So for now we will restrict our efforts 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.
Line 26: Line 23:
 * 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.		  * Integrating topics directly with the Upstream documentation. (This will have to wait until Project Mallard is implemented, otherwise there would be major merging and licensing problems.)
Line 32: Line 27:
 * 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").		 [:UbuntuHelp/PageStructure] describes in detail the desired structure for help pages.
Line 37: Line 31:
 1. Documentation team members should create and refine example pages using the desired structure.  1. Documentation team members should create and refine example pages, using DocBook markup to achieve the desired structure.
Line 39: Line 33:
 1. Documentation team members will work with upstream Yelp developers to implement an attractive and useful front page for Feisty.
Line 40: Line 35:

== Outstanding issues ==

Summary

To make Ubuntu's help more useful, we should rearrange the Ubuntu Desktop Guide so that each page is short and answers a specific question or explains a specific topic. We should also work with the Gnome documentation team to implement a useful front page for the help viewer, and to accelerate the development of their Project Mallard.

Rationale

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.

For more detail, see HelpfulHelp.

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 it is not implemented upstream and we do not have sufficient resources to implement it ourselves. Upstream plans to implement it as [http://www.gnome.org/~shaunm/quack/mallard.xml Project Mallard], which the GNOME Documentation team has been working on for the past year, but so far this is vaporware. (See also [http://norman.walsh.name/2005/10/21/dita Dita].)

So for now we will restrict our efforts 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 merging and licensing problems.)

Design

[:UbuntuHelp/PageStructure] describes in detail the desired structure for help pages.

Implementation

  1. Documentation team members should create and refine example pages, using DocBook markup to achieve the desired structure.

  2. The rest of the Desktop Guide should be rearranged to follow the style set by the example pages.
  3. Documentation team members will work with upstream Yelp developers to implement an attractive and useful front page for Feisty.

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

TopicBasedHelp (last edited 2008-08-06 16:29:22 by localhost)