TopicBasedHelp

Differences between revisions 1 and 7 (spanning 6 versions)
⇤ ← Revision 1 as of 2005-10-31 18:27:18 →
Size: 781
Editor: 187_220_103_66-WIFI_HOTSPOTS
Comment: summary
← 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 1: Line 1:
##(see the SpecSpec for an explanation)

 * '''Launchpad Entry''': https://launchpad.net/distros/ubuntu/+spec/foo		  * '''Launchpad entry''': https://launchpad.net/distros/ubuntu/+spec/topic-based-help
Line 5: Line 3:
 * '''Contributors''': MatthewPaulThomas
 * '''Packages affected''': 		 * '''Contributors''': MatthewPaulThomas, AndreasLloyd
 * '''Packages affected''': ubuntu-docs
Line 10: 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 14: Line 12:
== Use cases == 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.
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 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.)
Line 19: Line 26:

[:UbuntuHelp/PageStructure] describes in detail the desired structure for help pages.
Line 22: Line 31:
=== Code ===

=== Data preservation and migration ===

== Outstanding issues ==

== BoF agenda and discussion ==		  1. Documentation team members should create and refine example pages, using DocBook markup to achieve the desired structure.
 1. The rest of the Desktop Guide should be rearranged to follow the style set by the example pages.
 1. Documentation team members will work with upstream Yelp developers to implement an attractive and useful front page for Feisty.
 1. MatthewPaulThomas will work with the Gnome documentation team to specify the file format and markup language for Project Mallard in the next six months.

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)