TopicBasedHelp

Differences between revisions 14 and 15
⇤ ← Revision 14 as of 2006-11-23 12:04:46 →
Size: 4042
Editor: mail
Comment: trivial
← Revision 15 as of 2006-11-23 13:13:15 → ⇥
Size: 3859
Editor: 121-72-132-184
Comment: addresses Unresolved issues; some condensing
Deletions are marked like this. Additions are marked like this.
Line 8: Line 8:
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.		 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.
Line 14: Line 12:
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.		 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.
Line 20: Line 16:
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 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].)
Line 22: Line 18:
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. 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.
Line 26: Line 22:
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.
 1. 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.		  1. Help pages should be short and focus on a single topic. [:UbuntuHelp/PageStructure] describes in detail the desired format.
 1. 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.
Line 32: Line 27:
In relation to 1 above:  1. Documentation team members should create and refine example pages, using Doc``Book markup to achieve the desired structure. This will include:
  * learning whether to use Doc``Book'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.
Line 34: Line 32:
 * 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.		  1. 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. For example, working from the current Desktop Guide structure:
  * 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
Line 38: Line 47:
In relation to 2 above:  1. 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.
Line 40: Line 49:
 * 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.		  1. Ubuntu Documentation team members should work with upstream developers to implement an attractive and useful Yelp front page for Feisty.
Line 57: Line 51:
Other:  1. Kubuntu team members should get the packaging right so that the Kubuntu documents take on the structure decided above.
Line 59: Line 53:
 * 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.		  1. 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.

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 [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, 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. For example, working from the current Desktop Guide structure:
    • 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
  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)