TopicBasedHelp

Revision 14 as of 2006-11-23 12:04:46

Clear message

Summary

To make Ubuntu and Kubuntu's help more useful, we should rearrange the 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 and KDE documentation teams to implement a useful front page for the help viewer.

Rationale

The Ubuntu and Kubuntu documentation is currently written as manuals. 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

The Gnome Documentation team plans to implement a topic based help system 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].)

The Ubuntu/Kubuntu documentation teams do not have the resources to implement a topic based help system from scratch, so for now we should restrict our efforts to reorganizing the Desktop Guide and Server Guide, in order to make the structure of the documentation more discoverable for users.

Design

Two things.

  1. Concentrating on ensure pages presented to users are short and focus on a single topic. [:UbuntuHelp/PageStructure] describes in detail the desired structure for help pages.

  2. Split up the current Desktop and Server guides into a nice structure from which the user can choose a relevant section. For example, the homepage of the documentation wiki currently presents a nice selection of different "topics" which could form a basis for these.

Implementation

In relation to 1 above:

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

  • The rest of the Desktop Guide and Server Guide should be rearranged to follow the style set by the example pages.
  • Amend the relevant xslt to split up pages more than is currently done for the Ubuntu/Kubuntu material.

In relation to 2 above:

  • Work on a intuitive top level structure for the documentation. This would then appear in the Ubuntu/Kubuntu help viewers as a top level menu. For example, working from the current Desktop Guide structure might produce something like (total braindump list):

    * New to Ubuntu - common questions
* Linux Basics
* Using your Desktop
* Desktop Customisation
* Administrative Tasks
* Adding, Removing and Updating Applications
* Music and Video
* Internet
* Office
* Graphics and Pictures
* Games
* Programming
* Running Server Applications

  • Ubuntu - Documentation team members should work with upstream developers to implement an attractive and useful front page for Feisty.

  • Kubuntu - Get the packaging right so that the Kubuntu documents take on the structure as decided above.

Other:

  • MatthewPaulThomas should work with the Gnome documentation team to develop 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. An important consideration when doing so is to enable Ubuntu and Kubuntu documentation to be maintained together.

Outstanding Issues

* Whether to use docbook's <article> or <book> format for the new top level chapters. * How to deal with broken links which will appear when the sections are split off into separate documents.

Comments on this draft spec

Please write some user case examples - I can grasp the idea but not the implementation structure. DuncanLithgow