TopicBasedHelp

Summary

To make Ubuntu's 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 Project Mallard, and has been working on it for the past year, but so far this is vaporware. (See also 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, to make the documentation easier to navigate.

Design

  1. Help pages should be short and focus on a single topic. UbuntuHelp/PageStructure describes in detail the desired format.

  2. The current Desktop and Server Guides should be rearranged into a convenient structure for browsing by topic. The topics available from the front page should correlate with the topics displayed on the help wiki.

Implementation

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

    • learning whether to use DocBook's <article> or <book> format for the new top-level chapters

    • amending the relevant xslt to split up pages more than happens currently
    • becoming familiar with the syntax for linking to topics in other documents, not just in the same document.
  2. Meanwhile, team members should also work on understandable top-level categories for the help, to be presented on the front page of the Ubuntu and Kubuntu help viewers. To work on those, see TopicBasedHelp/TopLevelCategories.

  3. Once the previous two items are (mostly) done, the rest of the Desktop Guide and Server Guide should be rearranged to follow the decided style and structure.
  4. Ubuntu Documentation team members should work with upstream developers to implement an attractive and useful Yelp front page for Feisty.
  5. Kubuntu team members should get the packaging right so that the Kubuntu documents take on the structure decided above.
  6. 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.

Comments on this draft spec

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

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