Ubuntu Wiki

• Launchpad entry: https://launchpad.net/distros/ubuntu/+spec/topic-based-help

• Created: Date(2005-10-31T18:27:18Z) by MatthewPaulThomas

• Contributors: MatthewPaulThomas, AndreasLloyd

• Packages affected: ubuntu-docs

Summary

To make Ubuntu's help more useful, we should rearrange the Ubuntu Desktop and Server Guides 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 (the current GNU FDL and Creative Commons licenses have problems), 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. The Gnome Documentation team plans to implement it as [http://www.gnome.org/~shaunm/quack/mallard.xml Project Mallard], and has been working on it 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 should restrict our efforts to reorganizing the Desktop Guide and Server Guide, in preparation for splitting them into individual help pages. We should also incorporate relevant documentation from the Official Ubuntu Book and from Ubuntu Forums.

Out of scope:

• Integrating the Desktop Guide with upstream help such as the Gnome User Guide. (This will have to wait until Project Mallard is implemented, otherwise there would be major merging and licensing problems.)
• Breaking other upstream help into topic-based chunks. (Such a divergence from upstream would be a maintenance headache, and we should establish Ubuntu Help as a demonstration of the topic-based approach first.)

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 and Server Guide should be rearranged to follow the style set by the example pages.
3. Documentation team members should work with upstream Yelp developers to implement an attractive and useful front page for Feisty.

4. MatthewPaulThomas should work with the Gnome documentation team to specify the file format, markup language, and indexing/search requirements for Project Mallard over the next six months, so we can convert our help to the new format in the Feisty+1 cycle.