GOPW Halfway Report

Incredibly, my first GNOME summer is already halfway through, so it’s time for a progress report. Here are some of the things I’ve learned and the sub-projects I’ve worked on so far.

How GNOME Documentation is made

• The Docs Project has a wiki page on GNOME Live
• The GNOME Documentation team uses the new Mallard XML format for writing help
• Source files are stored on git.gnome.org
• general GNOME Desktop help in http://git.gnome.org/browse/gnome-user-docs
• help for applications in their /help/ directories, e.g., http://git.gnome.org/browse/empathy/tree/help/C
• GNOME help is available in HTML: http://library.gnome.org/users/
• Bugs and patches are tracked with bugzilla.gnome.org
• Discussions happen via email — gnome-doc-list@gnome.org and IRC — #docs on irc.gnome.org (GimpNet in Empathy)

All in all, the team seems great, and the tools are used effectively, although some of the process documentation and the style guide could be updated for the newbies’ benefit.

Literature overview

• Help usability is an active research field.
• There are several types of sources:
• journals (such as Technical Communication) and conference proceedings (such as SIGDOC)
• practical articles and resources in technical communication magazines
• books, both monographs like Carrol’s Minimal Manual and collections like The Art of Human-Computer Interface Design
• guidelines for commercial and free projects, such as the GNOME style guide http://developer.gnome.org/gdp-style-guide/stable/index.html.en
• Each stage of the documentation process has its own research area, e.g.:
• research of typical help use patterns
• design of documentation
• organization of the writing process
• evaluation methods, such as heuristics and testing
• There are many websites with resources on the subject, but only some of them are more-or-less current
• Online general usability resources:
• http://www.usability.gov/
• http://www.infodesign.com.au/usabilityresources
• http://www.useit.com/
• Help / documentation usability resources:
• http://www.writersua.com/index.html
• http://www.stcsig.org/usability/topics/docs-usability.html

To sum up my impressions, new theories and tools for writing help emerge all the time, but eventually some principles gain wide acceptance. So, at least in some aspects, documentation “best practices” exist, and we can use them.

Also, one of the big problems for help is that many people who would benefit from reading it don’t feel it’s worth the effort. On the bright side, the content and structure of the new GNOME help is already geared toward easier and quicker use. To improve this situation, we’ll need to ensure complete coverage, iron out any usability wrinkles, make getting context-specific help really easy, and give it some time.

A look at Empathy help

• The documentation was fairly easy to read and navigate.
• It addressed the questions I had, although it couldn’t solve a particular (rare) problem.
• For a more thorough review, I will use a checklist derived from the literature. I’m tentatively calling it the “Better help checklist”.

Better help checklist draft

• Compiled research results, practical guidelines and evaluation heuristics from 6 articles
• Sorted them by theme (such as structure, language, navigation)
• To Do:
• Categorize checklist items by level of application (entire system, section, topic)
• Improve the wording for better usability
• Finish writing a short explanation for each item
• Send the draft to gnome-doc-list for review

Advertisements