The GNOME Handbook of Writing Software Documentation

David Mason

Red Hat, Inc.

            <dcm@redhat.com>
          

Daniel Mueth


            <d-mueth@uchicago.edu>
          

Alexander Kirillov


            <kirillov@math.sunysb.edu>
          

This is a pre-release!

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

Revision History
Revision 0.99 04.10.2000

Table of Contents

Introduction
The GNOME Documentation Project
Notation and Conventions
About This Handbook
Getting Started Writing GNOME Documentation
Selecting A Document
Installing and Using DocBook
GDP Document Templates
Screenshots
Application Bugs
Using CVS
The GNOME Documentation System
The GNOME Help Browser
The GNOME Help Browser (GNOME-2.0)
Dynamic Document Synthesis(GNOME-2.0)
The GNOME Documentation Components
DocBook Basics
Introduction to DocBook
XML and SGML
Structure Elements
Inline Elements
GDP Documentation Conventions
Conventions for All GDP Documentation
Conventions for Application Documentation
Writing Application and Applet Manuals
Listing Documents in the Help Menu
Application Help Buttons
Packaging Applet Documentation
Applet Documentation Files
Adding Documentation to an Applet Menu
Writing Context Sensitive Help (coming in GNOME-2.0)
Referring to Other GNOME Documentation (coming in GNOME-2.0)
Basics of Documentation Style
Planning
Achieving a Balanced Style
Structure
Grammar and Spelling
Teamwork
Working With The GDP Team
Working With Developers
Finishing A Document
Editing The Document
Submitting The Document
Resources
Resources On The Web
Books
Mailing Lists
IRC
A Document Templates
Template 1: Application Manual
Template 2: Applet Manual For GNOME 1.x
Template 2: Applet Manual For GNOME 2.x

Introduction

The GNOME Documentation Project

Goals

The GNOME Documentation Project (GDP) aims to provide GNOME and GNOME applications with a complete, intuitive, and clear documentation system. At the center of the GDP is the GNOME Help Browser, which presents a unified interface to GNOME-specific documentation as well as other Linux documentation such as man pages and texinfo documents. The GNOME Help System provides a comprehensive view of documentation on a machine by dynamically assembling the documentation of GNOME applications and components which are installed. The GDP is responsible for writing numerous GNOME-related documents, both for developers and for users. Developer documentation includes APIs for the GNOME libraries, GNOME White Papers, GNOME developer tutorials, the GNOME Developer FAQ, the GNOME Developer's Website, and GNOME Handbook's, such as the one you are reading. User documentation include the GNOME User's Guide, the GNOME FAQ, and GNOME application documentation. Most GNOME applications have their own manual in addition to context sensitive help.

Joining the GDP

Documenting GNOME and all the numerous GNOME applications is a very large project. The GDP is always looking for people to help write, update, and edit documentation. If you are interested in joining the GDP team, you should join the gnome-doc-list mailing list . Read the section called “Getting Started Writing GNOME Documentation”, for help selecting a project to work on. Feel free to introduce yourself on the gnome-doc-list mailing list and indicate which project you intend to work on, or else ask for suggestions of important documents which need work done. You may also want to join the #docs IRC channel on irc.gnome.org to meet other GDP members and discuss any questions you may have. For a list of GDP projects and members, see the GDP Website.

Collaborating with the GDP

GNOME developers, packagers, and translators may not be writing GNOME documentation but will want to understand how the GNOME documentation system works and will need to collaborate with GDP members. This document should help to outline the structure of how the GNOME documentation system works. Developers who do not write the documentation for their applications are encouraged to find a GDP member to write the documentation. This is best done by sending an email to the gnome-doc-list mailing list describing the application, where it can be downloaded from, and that the developer(s) would like a GDP member to write documentation for the application. The #docs IRC channel on irc.gnome.org is another option for contacting GDP members.

Notation and Conventions

This Handbook uses the following notation:

/usr/bin Directory
foo.sgml Filename
command Command or text that would be typed.
replaceable "Variable" text that can be replaced.
Program or Doc CodeProgram or document code

About This Handbook

This Handbook is a guide for both writing documentation for GNOME components and applications and for properly binding and packaging documentation into GNOME applications.

This Handbook, like all GNOME documentation, was written in DocBook(SGML) and is available in several formats including SGML, HTML, PostScript, and PDF. For the latest version, see Getting The GNOME Handbook of Writing Software Documentation . Alternately, one may download it anonymously from GNOME CVS under gnome-docu/gdp.