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 help re-written into topic based help for GNOME 3.0:

(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.