in Documentation

Quack – An update on GNOME 3.0 Help

One of the big improvements for GNOME 3.0 is new user help.  The Documentation Team is using Mallard to re-write the GNOME User Guide and a number of applications help files as well.

In GNOME today, most help files are written in a very linear structure by chapter using Docbook XML.  If you’re a user looking for help, it’s not always easy to find the right chapter that contains the topic you’re looking for help with.

Topic based help aims to fix that.  And to write topic based help, the GNOME Docs team will be using Mallard, a new XML language written by Shaun McCance aka the GNOME Documentation Project’s Fearless Leader.

The hardest part about writing good help (in any markup) is planning, planning, planning.  What feature might the user need help with? Where will they get stuck? How should the topics be organized?

From there, you write help that’s in the second person in a conversational tone to help the user.  (And choosing the right words is important as well to help the localization teams out, too).

Let’s use Tomboy’s help to compare.

Tomboy help in GNOME 2.30 using Docbook:

Tomboy 2.30 Help

Tomboy help re-written into topic based help for GNOME 3.0:

Tomboy Help for GNOME 3.0

Tomboy help re-written in Mallard

(And there are a number of topics you can’t see in the screenshot such as Common Problems, Advanced Actions and What’s New.)

The goal is to help users get to the help they need fast.  There’s always been a bit of an in-joke that users don’t read the help.  We’re aiming to change that.  When they need help, we need to present it quickly and easily.  (Which also ties in to the work Shaun is doing in Yelp 3.0).

For GNOME 3.0, we are going to re-write the GNOME User Guide.  This will be a difficult challenge due to the amount of information currently in the guide as well as GNOME Shell and the user interface being in development and we need for it to stabilize before writing the docs.  Shaun, Milo and Phil did a lot of planning around the user guide at the Desktop Help Summit this past April in Chicago.

In addition to this herculean task, a number of applications are in process of getting new help or replacing their old help with topic based help, including:

  • Banshee
  • Brasero
  • Cheese
  • F-Spot
  • gLabels
  • Rhythmbox
  • Tomboy

On a personal note, I finished Tomboy’s help and started Banshee’s help this weekend on the plane coming back from the Marketing hackfest.  I’d also like to thank Harold Schreckengost who just joined the docs team last month and has already started, if not finished, topic based help for Brasero and F-Spot.  (I committed the F-Spot help tonight on his behalf in a new branch – docs).

If you’re an application developer and you know of your help being written or re-written in Mallard, please add it to the list on the wiki.  App maintainers also may need to re-work the way help is called from the menu and help the doc writers review any new documentation for accuracy.  (Thanks in advance!)

If you’re a documentation writer, please visit the page above as well for examples on how we plan our writing for help and the Docs wiki has a lot of other great information for getting started too.  Take it from me, writing in Mallard is much easier than Docbook, and now is a great time to get involved with the Docs team and writing new user help as we’re all learning the new language and we can make a big impact on GNOME 3.0.

  1. I just hope a stable version of Gnome Shell releases which is included in Ubuntu. As for the manual, it will be of help to new users and people switching over from Windows.

  2. Paul, I like how you’ve handed the topic descriptions. I sometimes think that the descriptions can be a bit redundant, but you’ve done a good job with them.

    One thing I notice is that the topic capitalization is a bit inconsistent (e.g., “Configure and Setup Sync,” and “Sync your Tomboy notes with other computers”), but I hope you don’t think that is nitpicking.

    One thing for sure is that this approach is 10x better than docbook.

  3. Chinmoy:

    I’m not sure what GNOME Shell and Ubuntu have to do with this blog post.

  4. Jim,

    Thanks.

    I still want to tweak the topic descriptions – you’re right on the inconsistencies. I have lots of excuses but no good ones. :)

  5. Chimony, Mark Shuttleworth has said both at last week’s Open Week & this week’s Ubuntu summit that Gnome Shell will not be the default in this fall’s Ubuntu release but it will continue to be available in the repositories (as is the case for Lucid & Karmic).

Comments are closed.