GNOME Documentation - Past, Present and Future

A white paper for GUADEC 4, Dublin, 16 - 18 June, 2003

Presented by: Pat Costello

Eugene O'Connor

Irene Ryan

Introduction

To put the development of the GNOME documentation into proper context, we need to briefly review the GNOME Documentation Project (GDP). The following are some key points about the GDP:

• The GDP mission is to provide the GNOME community with high quality documentation, including online Help, tutorials, application manuals, printed books, programming references, and style guidelines. Everything produced by the GDP is covered by the GNU Free Documentation License (GFDL).
• The GDP works with parallel teams in the GNOME project, such as developers and the usability team. We apply the GNOME Human Interface Guidelines (HIG) maintained by Calum Benson, Seth Nickell, and others. As part of this cooperative work, we attend UI reviews, for example.
• During the natural course of our work we uncover, define, and propose new terminology. We work with developers and the usability team to ensure the proper integration of accepted new terminology into the desktop and applications.
• The GDP tracks work-in-progress on the DocTable, at the following location:
  http://developer.gnome.org/projects/gdp/doctable--.html

GDP Roles

• The GDP consists of contributors ranging from individuals to teams from companies. Authors and maintainers of documentation are captured in the DocTable planning document. The coordinator, casting vote, and final arbiter in the GDP is John Fleck, Fearless Leader.
• The GDP develops, maintains, and publishes the GNOME Documentation Style Guide (GDSG): Pat Costello is the coordinator of the GDSG. An impressive list of GDP members have contributed to the GDSG over the past three years. Along with Pat Costello, John Fleck and Sasha Kirillov form the GDSG editorial team.
• The Recommended Terminology section of the GDSG is particularly important, as the terms are applicable everywhere in the desktop. Eugene O'Connor maintains this part of the GDSG.
• The GDP also publishes a manual to help contributors with the finer points of creating documentation, and integrating the documentation into the desktop build. Eric Baudais maintains the GNOME Handbook of Writing Software Documentation (GHWSD).
• Eric Baudais has also done a lot of work with stylesheets for GNOME documentation, along with Greg LeBlanc. The stylesheets are needed to generate correct HTML from documentation source files.
• The GDP provides templates for Help manuals to ensure that there is consistency of structure across the GNOME documentation set. Sasha Kirillov and Irene Ryan maintain the templates.

Past

To understand the present course of the GDP, we need to look at the development of GNOME documentation from some point in the past. The Sun documentation team has been involved in the GDP from the year 2000, so we have chosen to talk about the project from that time onwards. We came on board just prior to the release of the GNOME 1.4 desktop.

GDP Processes

• Style:
  • Work had begun on the GDSG, starting with some general guidelines and some DocBook information.
  • There were no specific guidelines or terminology recommendations.
  • The GHWSD provided basic getting started information.
• Templates:
  • Templates for applet and application manuals supported the DocBook 3.1 SGML format.
  • The templates contained various non-Help-related sections.
• Terminology development:
  • The decision-making process for terminology was by discussion on the gnome-doc-list.
  • This was a slow process, with no frame of reference on which to base the discussion, and often did not produce a clear recommendation.
  • While discussions were ongoing about terminology, writers who were working on manuals had to make their own decisions about terminology.
• GNOME integration:
  • There was some individual contact with other GNOME projects.
  • There was little formal cross-project interaction, for example between the usability project and the GDP.

Technical Aspects

In the year 2000, the GDP was at the following point in development:

• Writing tools: Documentation was produced using DocBook 3.1 SGML code.
• Stylesheets: Stylesheets were available to support DocBook 3.1.
• Help browser: The GNOME Help browser was in the process of being displaced by the Nautilus browser.
• Help links: The GNOME desktop had a limited number of Help buttons.

Desktop Help

The following desktop Help was available:

• User Guide for GNOME 1.0. User Guide issues:
  • The User Guide needed to be substantially revised and updated for GNOME 1.4. More importantly, we needed to implement a regular update process that would cater for future revisions of the desktop.
  • Terminology in the User Guide was often inconsistent with terminology in the desktop, and in the individual application Help manuals.

Application Help

Help manuals were available for most applets and applications for the GNOME 1.0 desktop.

Help manual issues:

• Most of the Help was function-oriented, describing the menus and other interface components of applications, without providing much information about how to use the applications.
• The level of updating to the Help manuals was inconsistent. Similarly to the User Guide, we needed a process to keep the Help manuals for applications and applets up-to-date.
• All manuals contained a lot of non-Help-related information. This made it difficult for users to scan the manuals quickly to find a specific piece of information.
• Terminology and writing style varied considerably across the set of Help manuals.
• Terminology in Help manuals was also inconsistent with terminology in the desktop.

Localization

Limited localization work was being done for documentation.

The following issues presented potential localization difficulties:

• Inconsistent terminology
• Presence of non-Help-related information
• Colloquial language

Present

GDP Processes

• Style:
  • The GDP now has an extensive, comprehensive style guide, the GDSG.
  • The GDSG contains general style guidelines. For example, the GDSG contains recommendations that specify to use the present tense, to avoid the passive voice, to use active verbs in the imperative form for procedural steps, and so on.

  The GDSG also contains information on specific areas, such as information design, writing for localization, and writing documentation for UIs. For example, the information design chapter contains information on when to use numbered lists, bulleted lists, tables, and so on. The information design chapter also contains information on the use of parallel grammatical constructions.

  The writing for localization chapter contains recommendations on how to write to facilitate the work of translators. For example, this chapter suggests to avoid use of the indefinite pronoun it, as translators might be confused about the article to which the pronoun refers.

  • The GDSG contains an extensive section about recommended terminology. This section now contains 268 terms, including 126 GNOME-specific entries.
  • The GHWSD is a technical guide to writing documentation, and now contains the DocBook information that was originally in the GDSG.
  • The GHWSD is up-to-date and contains practical advice on how to use the GDP writing tools.
  • The GHWSD also tells you how to deal with screenshots, indexing and other topics. For example, the GHWSD tells you how to use GIMP to add callouts to screenshots, in a way that facilitates the work of translators.
• Templates:
  • Revised templates are now available for applet and application manuals.
  • Revised templates encourage consistent use of task-oriented information. The manuals are structured according to the tasks that users want to perform, rather than by functionality.
  • Revised templates put all non-Help-related information into the About This Document page. Information that is possibly not of immediate interest to the user, such as legal information and revision history, is in this page.
• Terminology development:

  The process for developing new terminology is now as follows:

  1. Writer discovers the need for a new term.
  2. Writer discusses a provisional definition and usage for the new term with a peer group.
  3. Writer puts the suggested new term to the GDSG editorial team.
  4. Writer sends the term to recommended terminology coordinator (Eugene) for inclusion in the terminology section of the GDSG.
  5. Recommended terminology coordinator adds the term to the GDSG and notifies the
     gnome-doc-list about the new term.
  6. Term passes into general use. The term can be amended from experience in use.
• GNOME integration:
  • Increased cooperation between developers, usability engineers, and the writers.
  • Writers regularly log bugs that they find while documenting an application. Writers can be very useful to developers. Writers can identify where UI labels can be improved. If it is difficult for a writer to document an application, then this suggests that the UI of the application can be improved. Also, writers have a top-level view of the desktop, so they can identify inconsistencies between applications.
  • Writers are asked by usability engineers and developers for terminology input during UI development.
  • Writers take part in the UI reviews.

Technical Aspects

The current snapshot for technical aspects is as follows:

• Writing tools: Documentation is now produced using DocBook 4.1.2 XML. The GDP moved from DocBook SGML to XML to benefit from wider industry usage of XML.
• Stylesheets: Stylesheets now support DocBook 4.1.2 XML. Eric Baudais did a lot of work to ensure that the stylesheets support the new Help templates.
• Help browser:

  The main aspects of the Help browser story up to now are as follows:

  • Nautilus proved to be too slow to work with the Help files.
  • A lightweight Help browser called Yelp was developed to display Help and documentation. Yelp uses ScrollKeeper, so all the documentation is registered in ScrollKeeper.
  • Some larger manuals still take some time to load in Yelp. You can pregenerate the HTML files from the XML sources, so that Yelp does not have to do the conversion when the user calls the Help.
  • The trade-off with using Yelp, however, was that multichapter manuals took a long time to display. To resolve this issue, we developed a workaround by breaking up multichapter books into individual chapters for display in Yelp. This allows the information to be displayed more quickly, but creates a navigation issue. The chapters of the User Guide are displayed in Yelp in no particular order.
  • We can recombine multichapter books to resolve the navigation issue with larger books. This has a negative performance impact on performance. However, this performance impact does not occur if we use pregeneration by default.
• Help buttons: The GNOME desktop now has a comprehensive set of Help buttons and menu items that link to the relevant parts of the User Guide.

Desktop Help

The current desktop Help situation is as follows:

• We have issued seven revisions of the User Guide for the following versions of GNOME:
  • GNOME 1.4
  • GNOME 2.0
  • GNOME 2.2
  • GNOME 2.2.1
• We now have a process for developing the User Guide. The process is as follows:
  1. Writer updates the User Guide.
  2. Writer commits User Guide to CVS.
  3. Writer makes the User Guide available in various formats for Steve Fox to place on the
     http://www.gnome.org/learn web page.
  4. Writer notifies the gnome-doc-list, requesting review comments.
  5. Writer incorporates GDP feedback into the User Guide. Useful feedback is frequently provided by GDP members.
• We now aim to have a current User Guide for every stable GNOME desktop release.
• Other new guides that are now available for use as desktop Help include:
  • Accessibility Guide
  • Introduction to GNOME
  • System Administration Guide
  • Man pages: currently in SGML

Application Help

The current application Help situation is as follows:

• Updated Help manuals integrated into the GNOME 2.0 and GNOME 2.2 desktops.
• Help manuals for the GNOME 2.4 desktop are in development.
• Manuals are now written using a task-oriented approach.
• Help manuals that follow GDSG guidelines are very easy to translate.

Localization

• Translated versions of the User Guide are available for use as desktop Help in 11 languages. Sun Microsystems provided the following translations: German, Spanish, French, Italian, Swedish, Korean, Japanese, Chinese Simplified, Chinese Traditional. Volunteer translators provided translated versions of the User Guide in Hungarian and Romanian.
• Translated versions of the applet and application manuals are available in nine languages, namely: German, Spanish, French, Italian, Swedish, Korean, Japanese, Chinese Simplified, Chinese Traditional.

Future

GDP Processes

From a process point of view, we would like to see the following developments:

• Style:
  • Improve the update process for the GDSG on the GDSG website.
  • Strive for universal GNOME compliance to guides such as the GDSG and HIG.
  • Combine the GDSG with other GNOME guides, into a super-library of guidelines.
• Templates:
  • Develop a template for a multichapter book.
• Terminology development:
  • Extend usage of the GDP terminology process to include GNOME developers.
  • Continue to develop GNOME terminology as more GNOME applications are developed. We expect to add several Evolution terms in the near future.
• GNOME integration:
  • Better planning of GDP jobs.
  • Complete the process of integration.
  • Developers should leverage the full benefit of writers testing their applications prior to release.

Technical Aspects

From a technical point of view, we would like to see the following future developments:

• Writing tools:
  • Free software WYSIWYG writing tool for DocBook 4.1.2 XML.
• Stylesheets:
  • Develop a polished stylesheet, with the involvement of graphic designers. Compare the following stylesheets:

    Yelp Stylesheet

    

    KDE Stylesheet

    

• Help browser:

  Some of the things we look forward to having:

  • Recombined multichapter books in Yelp display.
  • Improved front-end with search and indexing functions.

    KDE Help Center

    

• Help links:
  • Provide links to the System Administration Guide.
  • Provide links to the Accessibility Guide.

Desktop Help

The future plans for the desktop Help are as follows:

• Future revisions of User Guide.
• Develop the System Administration Guide.
• Extend accessibility Help, include applications such as GOK and Gnopernicus.
• Extend Help to include broader topics, such as Developer Guides.
• Man pages provided in XML format and displaying in Yelp, as well as at the command line.
• Measure and improve the usability of Help.
• Encourage a reduced-text approach to documentation and Help. This approach will depend on the following factors:
  • Rigorous application of the GDSG. Conscious objective for writers to reduce text without losing concepts.
  • Information-driven UI design.
  • Use of context-sensitive Help.
• Context-sensitive Help. This is a great idea, and we are keen to contribute.

Application Help

The future plans for the application Help are as follows:

• Existing manuals updated for the GNOME 2.4 desktop.
• Help manuals written for new applications planned for the GNOME 2.4 desktop.

Localization

From a localization point of view, we would like to see the following future developments:

• More language versions of the documentation.
• Shorter time interval between the English language release and the other language releases.
• Faster translation times due to modular documentation and reduced text approach.
• Machine translation.

Summary

• Produce high-quality, up-to-date documentation for the GNOME Desktop, applets, and applications.
• Improve the look and feel of the Help browser.
• Work more closely with developers and usability teams to maximize our combined effectiveness in developing an information-driven approach.
• Promote the GDSG as the foremost style standard in the world for free software. We want to achieve industry-wide recognition, and thereby establish GNOME as a benchmark for everyone else.

Conclusion

• Enhance the user experience in using the GNOME Desktop, applets, and applications.
• Contribute to the GNOME Desktop being the desktop environment of choice for users worldwide.

Questions?