This is basically premised on the idea that books are great to read while sitting on the toilet, or to get a general overview of Ubuntu, but they are not good for help systems, because when a user opens the help system, he/she/it/they is looking for the answer to a SPECIFIC QUESTION.


The solid base of documentation that has been established for the Dapper release means that the documentation team, like the distro team, could do something adventurous for the next release. Together with the possibility of directly exporting wiki pages to docbook articles, a possible way to go might be to bin the upstream categorisation that currently forms the front page of the help system, which everybody knows is horribly confusing, and write our own, aimed at giving the users an all round better help experience by making things easier to find.


This would involve:

  • Writing our own front page and series of second level index pages for the help system (see below)
  • Attempting more integration of upstream material
    • It should be possible to create links in our documents to the categories of upstream documentation that appear in Yelp using something like:

      <ulink url="x-yelp-toc:#ApplicationsMultimedia">clickme</ulink>
  • Adopting a more compartmentalised structure for help, rather than focusing on books - each section would have a number of articles. This would involve:
    • Converting much of the existing documentation we have (Desktop guide, Server guide) to articles, or alternatively simply linking to the various parts of those guides in our index pages.
    • A big part of this plan would be to add articles downloaded from the wiki using the Moin2Docbook converter tools, and including links to those articles in our new index pages.

In the top level index, I would envisage something like the following sections (section titles in bold, my explanation of what they are in italics)

  • Introduction to Ubuntu - much of the substance from the current "About Ubuntu"

  • Installing, Removing and Upgrading Software - the current "add-applications" chapter from the desktop guide

  • Using your desktop - much of the current "Common Tasks" chapter in the desktop guide, some things from the Official Book, plenty of integration with the Gnome User Guide (preferably patched for Ubuntu), and including links to the upstream manuals of other desktop applications

  • Configuring your desktop - the rest of common tasks, things from the DesktopGuide/config-system/desktop tips section.

  • Setting up hardware - printers, graphics cards, ipods, whatever.

  • Administering your system - the rest of config-system chapter from the desktop guide, articles from the wiki

  • Setting up server applications - most of the substantive chapters from the server guide, articles from the wiki

  • Securing your computer - partly stuff from the server guide, partly new stuff on security, partly articles from the wiki

  • Finding more help - stuff about finding further help from the community or commercial support

  • Contributing to Ubuntu - stuff about contributing, including integration with the Packaging Guide

Obviously, these are totally work in progress and for brainstorming purposes only. We'd need to carefully lay out the structure

Pros and Cons

This approach would have the following advantages:

  • Users don't have to guess the difference between the first half and the second half of the current front page of the help system
  • More integrated documentation - upstream documentation currently gets very little exposure because it isn't integrated into the Ubuntu documentation.
  • Bringing in articles from the wiki would be easier
  • Pushing our documentation into the wiki in an integrated way would be easy (the wiki and the help centre would be potentially very similar)

There are the following potential disadvantages:

  • The translation system would have to be carefully worked out
  • We would have to either abandon the idea of producing publishable books, or alternatively doing the manual work to compose a book from the material outlined above
  • Some hard work required

MatthewEast/HelpfulHelpVersionMinusOne (last edited 2008-08-06 16:29:33 by localhost)