GNOME Handbook of Writing Software Documentation V1.0.2

This Handbook uses the following notation:

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

This Handbook is not a guide for writing developer documentation. If you can read C and wish to write developer documentation take a look at GTK+ Reference Documentation Project.

This Handbook, like all GNOME documentation, was written in DocBook(XML) and is available in several formats including XML, HTML, PostScript, and PDF. For the latest version, see http://library.gnome.org/devel/gdp-handbook/stable/. Alternately, one may download it anonymously from GNOME SVN under gnome-devel-docs/trunk/gdp-handbook.

DocBook is a markup language, like HTML, for technical and computer documentation, papers, and books. The GNOME Documentation Project uses DocBook to mark up GNOME documentation. The GDP currently uses version 4.1.2 of DocBook. DocBook SGML is used with gtk-doc for developer documentation while DocBook XML is used for end user documentation.

The main advantage of DocBook is its single-source multiple-output nature. Only one DocBook source file is needed to make many different outputs. From the same DocBook file the GDP lets the user view the documentation as HTML with Yelp and can provide a print copy, usually in PDF.

The GDP uses the XSL language to exploit DocBook's multi source nature. XSLT stylesheets convert DocBook into HTML, which Yelp displays. XSLT stylesheets are also used to convert DocBook into FO, an XML print specification, which is in turn converted to PDF or PS files. If any other format is needed the GDP could use an XSLT stylesheet to convert the DocBook files into another format such as man or info pages.

DocBook focuses on the document content, leaving presentation details to XSLT. For example all the applications within DocBook use the <application> tag. The stylesheets determine how the text inside the tag looks. Authors need not concern themselves, for example, with whether all applications will be in bold text or italics or whether the applications should not have any special formatting, focusing instead on what ideas the documentation should convey to the readers.

At the core of the GNOME help system is Yelp. Yelp provides a unified interface to several distinct documentation systems on Linux/Unix systems: man pages, info pages, Linux Documentation Project (LDP) documents, GNOME application documentation, and other GNOME documents.

Yelp works by getting a list of all documentation installed on your system from Scrollkeeper, documentation cataloging system used by GNOME, LDP, and other projects. Thus, the documentation that appears in the Yelp is specific to each computer and will typically only represent software that is installed on the computer.

GNOME uses the documentation presented by all the various GNOME components and applications installed on the system to present a complete and customized documentation environment. Yelp describes only components which are currently installed on a users system. Some of this documentation, such as the User's Guide, will be combined in such a way that it appears to be a single document.

By using such a system, you can be sure that any GNOME application you install that has documentation will show up in the index, table of contents, and any search you do in the help browser.

Yelp also integrates the conversion from DocBook to HTML. Yelp takes the DocBook document and runs a XSL processor, xsltproc, which uses a stylesheet to convert the DocBook file to a HTML file. Yelp also uses the GDP's own stylesheets on top of Norman Walsh's stylesheets. This allows the appearance of the all GNOME documentation to change with only altering one specific stylesheet. Using a custom stylesheet gives GNOME a custom help environment.

Scrollkeeper works with Yelp providing Yelp with the location of the local documentation, a TOC for that document, searching, and indexing abilities based on metadata gathered about the document. Scrollkeeper is a document cataloging system using Open Source Metadata Framework (OMF) files to provide metadata about each document installed in Scrollkeeper's catalog. Scrollkeeper is only meant to catalog documentation available locally on the user's system.

Scrollkeeper uses metadata from OMF files provided with each piece of documentation to categorize the document in its catalog. This catalog is then accessed by Yelp to build the links when Yelp starts up. Currently the OMF files aren't used for anything else, but in future versions of Scrollkeeper it will be utilized.

Scrollkeeper uses DocBook <indexterm> tags in the documentation to build an index. The index is a collection of words which refer to a specific document. In Yelp you can search through these words and view the document they coorespond to.

Subversion (SVN) is a tool that allows multiple developers to concurrently work on a set of documents, keeping track of the modifications made by each person. The files are stored on a server and each developer checks files out, modifies them, and then checks in their modified version of the files. Many GNOME programs and documents are stored in the Subversion repository. The GNOME Subversion server allows users to anonymously check out files. Most GDP members will access the repository without a login to download the most up-to-date version of documentation or programs. Modified documents will typically be emailed to the the application developer. Core GDP members may also be granted login privileges so they may commit modified files directly to the Subversion repositories. Below is a simple tutorial which will take you through the basics of using Subversion. A more complete guide is Version Control with Subversion.

The most frequently asked question of new contributors who join the GDP is “which document should I start with?”. Because most people involved are volunteers, we do not assign projects and applications to write documents for. The first step is all yours - you must decide what about GNOME interests you most and find out if it has complete documents or not.

It is also important to spend some time with GNOME to make sure you are familiar enough with it to be authoritative in your writing. The best way to do this is to just sit down and play with GNOME as much as possible before starting to write.

The easiest way to get started is to improve existing documentation. If you notice some inaccuracies or omissions in the documentation, or you think that you can explain the material more clearly, just send your suggestions to the author of the original documentation or to the GNOME documentation project at <gnome-doc-list@gnome.org>.

All documentation for the GNOME project is written in XML using the DocBook DTD. There are many advantages to using this for documentation, not least of which is the single source nature of XML. To contribute to the GDP you should learn to use DocBook.

There isn't a standard set of packages to install DocBook XML and make it work locally. Each distribution installs DocBook XML a bit differently with various degrees of support for needed features.

			# apt-get install libxslt1 
			# apt-get install docbook-xsl
		  

There are three tools used with DocBook documents. Xmllint checks the documentation to make sure it is valid DocBook and follows all the rules of XML and the DTD. Xsltproc transforms the document from DocBook to a variety of document formats, including HTML, using XSL stylesheets. Xmlcatalog generates, updates, and checks to make sure the XML catalog is working. You may have used these tools installing DocBook. This isn't meant to be a complete guide to these tools, but an introduction to famaliarize you with the common DocBook tools. If you want more information about any of them consult http://xmlsoft.org or view their respective man pages.

Templates for various types of GNOME documents are found at the GDP Document Templates website. They are kept in SVN at gnome-doc-utils/trunk/data/templates. These templates are meant to guide you through the process of making documentation. They contain the structure of the articleinfo section. The basic structure of a document is outlined. Many different elements are marked up in DocBook such as itemized lists, variable lists, and figures. It is okay to change the templates to fit the application you are writing documentation for. Changing the format of the articleinfo section is not recommended as the output will not look nice.

GNOME 2 documentation is written in DocBook XML, version 4.1.2.

We use DocBook because it provides structured semantic markup, allowing publication in a variety of media. We use XML because of the more flexible tool kit available to use with it.

The GDP Style Guide should be read in conjunction with this document. The Style Guide tells how to write documentation, ways to structure the documentation, and technical writing techniques. The GDP Style Guide is located at http://library.gnome.org/devel/gdp-style-guide/stable/.

Most GNOME documents will have screenshots of the particular applet, application, GNOME component, or widget being discussed. As discussed previously all images for GNOME documentation should be in the PNG format. Alternatively if you wish the documentation to be printed you should also include the same images in EPS format. For the basic DocBook structure used to insert images in a document, see Section 3.7.1 ― Screenshots in DocBook below.

<figure id="id">
  <title>My Picture</title>
  <screenshot>
    <mediaobject>
      <imageobject>
        <imagedata fileref="myfile.png" format="PNG"/>
      </imageobject>
      <textobject>
        <phrase>Acessibility description</phrase>
      </textobject>
    </mediaobject>
  </screenshot>
</figure>
   

Documentation authors tend to investigate and test applets and applications more thoroughly than most users. Often documentation authors will discover one or more bugs in the software. These bugs vary from small ones, such as mis-spelled words or missing About dialogs in the menu, to large ones which cause the applet to crash. As all users, you should be sure to report these bugs so that application developers know of them and can fix them. The easiest way to submit a bug report is by using Bug Buddy located in Applications ▸ Programming ▸ Bug Report Tool.

To understand DocBook, a basic understanding of SGML and XML is helpful.

SGML stands for Standard Generalized Markup Language and is one of the first markup languages ever created. A different, but similar markup language is XML which stands for Extended Markup Langauge. XML extends and structures SGML in ways which were optional using SGML. Both use what are called Document Type Definitions (DTD) to define document structural types such as HTML and DocBook. A DTD specifies document elements which are delimited by angle brackets, < and >, and document text is then marked by both beginning and ending elements. Using the DocBook DTD, for example, one marks up a title with <title>The Title</title>. The DTD (in the case of the GDP, DocBook) also defines rules for how the elements can be used. For example, if one element can only be used when embedded within another, this is defined in the DTD.

A XML file is just a plain ASCII file containing the text with the markup specified above. To convert it to some easily readable format, you need special tools. The GDP uses xsltproc, a free converter which converts the DocBook file into browser readable HTML using XSL stylesheets. Yelp is used to run xsltproc and then display the resulting HTML in a user friendly format. You can read more about DocBook in Section 3.3 ― Using DocBook Tools.

The final appearance of the output (e.g. PostScript or HTML) is determined by a stylesheet. Stylesheets are files, written in a special language (XSL — Extended Specification Language or DSSSL — Document Style Semantics and Specification Language), which specify the appearance of various DocBook elements, for example, what fonts to use for titles and various inline elements, page numbering style, and much more. You need to install a common collection of stylesheets in Section 3.2 ― Installing DocBook (Norman Walsh's modular stylesheets). The GNOME Documentation Project uses a customized set of stylesheets on top of Norman Walsh's version.

The advantage of specifying the structure of a document with XML instead of specifying the appearance of the document with a typical word processor, or with HTML, is that the resulting document can be processed in a variety of ways using the structural information. Whereas formatting a document for appearance assumes a medium (typically written text on a standard-sized piece of paper), XML can be processed to produce output for a large variety of media such as text, postscript, HTML, Braille, audio, and potentially many other formats. This assumption of a specific media makes translating documents not written in XML very difficult.

Using elements contained in a document to structure the text of that same document also allows search engines to make use of that information. For example, if you are searching for all documents written by the author “Susie” your search engine could be made smart enough to only search <author> elements, making for a faster and more accurate search.

Using a stylesheet to determine the overall appearance of the output, rather than the DTD or the XML document, allows everyone in the project to create documents with the same look just by using the same stylesheet. It also allows the look to be updated just by modifying that one stylesheet.

As stated before, the GDP uses the DocBook DTD. For a list of introductory and reference resources on DocBook, see Appendix A ― Resources. The following sections also provide convenient instructions on which markup tags to use in various circumstances. Be sure to read Section 5 ― GDP Documentation Guidelines for GDP documentation-specific guidelines.

DocBook can be used to write many different documents. Glossaries, FAQs, indexes, books, and articles are some of the documents which can be written. To start the type of document you will need to enclose the document in the appropriate tag. You will be able to tell the type of document from the first tag. For books you will enclose the document in the <book> tag and for articles you will enclose the document in the <article> tag.

DocBook documents contain meta data, data which describes the document, typically at the beginning of the document. This meta data will include copyright notices, author information, revision history, and release information. The meta data is enclosed within the info tags. For books you will enclose the meta data with the <bookinfo> tag and for articles you will enclose the meta data in the <articleinfo> tag.

Throughout this chapter a full article will be produced showing you how to write a full article in DocBook. So far we have

<article>
  <articleinfo>
  This will contain some information about the document.
  </articleinfo>
  This is the body of the document.
</article>

      

<article>
  <articleinfo>
  This will contain some information about the document.
  </articleinfo>

  <sect1>
    <title>DocBook Example</title>
    <para>
      This is an example of using DocBook for the most basic type of
      document.  The article just has one section and one paragraph.
    </para>
  </sect1>
</article>

	

<copyright>
  <year>2002</year>
  <holder>Eric Baudais</holder>
</copyright>

	

<authorgroup>
  <author>
    <firstname>Eric</firstname>
    <surname>Baudais</surname>
    <affiliation>
      <orgname>GNOME Documentation Project</orgname>
      <address>
        <email>baudais@kkpsi.org</email>
      </address>
    </affiliation>
  </author>

  <author>
    <firstname>John</firstname>
    <surname>Doe</surname>
    <affiliation>
      <orgname>Free Software Foundation</orgname>
      <address>
        59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
        <email>john.doe@gnu.org</email>
      </address>
    </affiliation
  </author>
</authorgroup>

	

<legalnotice>
  <title>Legal Notices</title>

  <para>
    Permission is granted to copy, distribute and/or modify this
    document under the terms of the GNU Free Documentation
    License (GFDL), 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 can find
    a copy of the GFDL at this <ulink type="help"
    url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
    distributed with this manual.
  </para>
</legalnotice>

<releaseinfo>
  This is version 1.0.0 of DocBook Basics documenting version 4.1.2 of
  DocBook XML.
</releaseinfo>

	

<article>
  <articleinfo>

    <copyright>
      <year>2002</year>
      <holder>Eric Baudais</holder>
    </copyright>

    <authorgroup>
      <author>
        <firstname>Eric</firstname>
        <surname>Baudais</surname>
        <affiliation>
          <orgname>GNOME Documentation Project</orgname>
          <address>
            <email>baudais@kkpsi.org</email>
          </address>
        </affiliation>
      </author>

      <author>
        <firstname>John</firstname>
        <surname>Doe</surname>
          <affiliation>
          <orgname>Free Software Foundation</orgname>
          <address>
            59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
            <email>john.doe@gnu.org</email>
          </address>
        </affiliation
      </author>
    </authorgroup>

    <legalnotice>
      <title>Legal Notices</title>

      <para>
        Permission is granted to copy, distribute and/or modify this
        document under the terms of the GNU Free Documentation
        License (GFDL), 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 can find
        a copy of the GFDL at this <ulink type="help"
        url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
        distributed with this manual.
      </para>
    </legalnotice>

    <releaseinfo>
      This is version 1.0.0 of DocBook Basics documenting version 4.1.2 of
      DocBook XML.
    </releaseinfo>

  </articleinfo>

  <sect1>
    <title>DocBook Example</title>
    <para>
      This is an example of using DocBook for the most basic type of
      document.  The article just has one section and one paragraph.
    </para>
  </sect1>
</article>

	

DocBook has many other tags to structure a document than sections and paragraph. Notes, figures, lists, and tables can all be included into a document and are as much a part of the way a document is structured as sections and paragraphs. An explanatory figure or table in the right place will enlighten the reader and enhance the appearance and readability of the document. The GNOME Documentation Style Guide talks more about when and where to use these effectively. Some of these are easy to use with DocBook while others take a while to master.

<tip>
<title>DocBook Validation Tip</title>
  <para>
    To validate DocBook without displaying the document, add the
    argument <parameter class="option">--noout</programlisting> to the
    <application>xmllint</programlisting> command.
  </para>
</tip> 

4.3.2.  Screenshots and other Figures

To include screenshots and other figures, use the following tags:

<figure id="app-FIG-shot1">
 <title>Screenshot</title>
 <screenshot>
  <mediaobject>
   <imageobject>
    <imagedata fileref="figures/example_screenshot.png" format="PNG"/>
   </imageobject>
   <textobject>
     <phrase>Shows the application screenshot with several buttons.</phrase>
   </textobject>
   <caption>
    <para>Screenshot of a program</para>
   </caption>
  </mediaobject>
 </screenshot>
</figure>
	

replacing example_screenshot with the actual file name (without extension). The result will look like this:

Figure 1 Screenshot

Screenshot of a program

<programlisting>
[Desktop Entry] 
Name=Gnumeric spreadsheet
Exec=gnumeric 
Icon=gnome-gnumeric.png 
Terminal=0
Type=Application
</programlisting>
	

[Desktop Entry] 
Name=Gnumeric spreadsheet 
Exec=gnumeric
Icon=gnome-gnumeric.png 
Terminal=0 
Type=Application
	

<screen>
<prompt>bash$</prompt><userinput>make love</userinput> 
make: *** No rule to make target `love'. Stop.
</screen>
	

bash$make love  
make: *** No rule to make target `love'.  Stop.
	

All GNOME documentation should conform to XML syntax requirements, which are stricter than SGML ones.

Section IDs are unique identifiers that you assign to each section of an XML file. You can use the section IDs to cross-reference sections.

The following sections contain suggestions as to how to write section IDs in XML files. The only real requirement for writing section IDs is that the IDs must be unique within a document.

All GNOME documentation should contain the names of all documentation authors who have worked on the document. The email address of all authors should also be included. Even if you totally rewrote the documentation you still need to include the names of any authors of previous documentation for the specific application, applet, component, or widget.

Application documentation should contain a copyright notice, stating the licensing terms. It is suggested that you use the GNU Free Documentation License. You could also use some other license allowing free redistribution, such as GPL or Open Content license. If documentation uses some trademarks (such as UNIX, Linux, Windows, etc.), proper legal junk should also be included (see templates).

If there is existing documentation then the author's copyright notice and license must be used. This is to ensure that licenses and copyrights stay intact from version to version of the application and documentation.

If you decide to use the GNU Free Documentation License, then all you need to do include the file legal.xml as a system entity (see templates). Otherwise you need to mark up the license you are going to use and include it in place of legal.xml.

All GNOME documentation should contain the names of all previous documentation titles along with the current title for the documentation. The current documentation title should indicate the version of the documentation. The revision history should also contain the authors and their email addresses for the documentation they wrote and the publisher of the documentation. This allows anybody to see how many revision the current documentation has undergone.

The revision history can also contains notes in the description for the specific version of the documentation. If the author rewrote the documentation from scratch this should be indicated in the revision description. Any extra descriptions need to be carried over to a new version of the documentation — see the templates for an example.

Application documentation should identify the version of the application for which the documentation is written. This information should be included in the <releaseinfo> tag:

<releaseinfo>
This manual describes version 1.56 of gfoobar.
</releaseinfo>
	  

All GNOME documentation must include information about the publisher of the document. This will always be the GNOME Documentation Project (see templates).

The GNOME Documentation Style Guide should be followed at all times in writing and editing GNOME Documentation. It contains writing tips, word usage, and grammatical errors common in technical writing. You should read it before you start writing and use it as the authoritative resource for writing style. To obtain a copy of the GNOME Documentation Style Guide go to http://library.gnome.org/devel/gdp-style-guide/stable to view it.

All GNOME applications must contain information about the license (for software, not for documentation), either in the “About” box or in the manual.

Application documentation should give an address for reporting bugs and for submitting comments about the documentation (see templates for an example).

The Uniform Resource Identifier (URI) is made up of three parts: the schema, the document and the id. The schema declares the type of document. Some of the well known schemas are: http://, ftp://, file://. There are three specific schemas identifying documentation in GNOME 2. The schema ghelp: identifies GNOME documentation. The schema man: is used to reference man pages and the schema info: identifies info pages. Yelp only uses the schemas ghelp:, man: and info: to cross reference documentation you must use one of those three schemas.

The second part of the URI is the document. This is really the path to the document and identifying the document itself. You can either give the full path to the document on the computer, give the filename of the document, or just give the appid. It is not recommended to use the full path of the document to reference documentation. This will lead to broken links and heartaches. You should always either use the name of the document (e.g. gedit.xml) or use the appid to reference the main documentation (e.g. gedit).

The third part of the URI is the id. The id is the unique DocBook id made for every section. For more information on section ids see Section 5.2 ― Section IDs. The id is optional, but will let you choose where in the document the reader will look instead of placing the reader at the table of contents. It is recommended to use ids in the URI to accurately direct the reader to a specific portion of the document.

The three parts of the URI are put together to cross reference documentation in GNOME. The URI is formed by placing the schema first, followed by the appid or filename of the document. A question mark is placed after the appid, but before the section id. Then the section id is put after the question mark. The complete URI looks like:

ghelp:gedit?intro
	  

Adding a link to a different GNOME help document is not hard. This is done using the “ghelp:” URI scheme. This works for documents which are shipped as XML. To cross reference another GNOME document, use:

<ulink type="help" url="ghelp:user-guide?gosbasic-2">text</ulink>

To link within the current document, you need only specify the section id you wish to link to, but the DocBook syntax is different. To create a link that displays the section number and name, use:

<xref linkend="intro" />

<link linkend="intro">text</link>

Adding a link to a manpage in a GNOME document is done using the “man:” URI scheme. To cross reference a manpage, use:

<ulink type="help" url="man:foo">text</ulink>

Adding a link to an infopage in a GNOME document is done using the “info:” URI scheme. To cross reference a manpage, use:

<ulink type="help" url="info:foo">text</ulink>

To link to web pages, use:

<ulink type="http" url="http://www.gnome.org">GNOME Web Site</ulink>

Documentation in GNOME application repository and packages should be kept under help/locale/, where locale is typically replaced with “C” for the default (English) documents or the locale for other documents. In some cases, “doc” is used in place of “help” however it is preferrable to use “help” to remain consistent with the path under which these documents are installed.

Most applications will have screenshots, images, or other figures. To keep the directories reasonably clean and easy to navigate, screenshots, images, and other similar items should be placed in a directory called figures. While in some cases the directory is called images since most figures consist of images (well, screenshots really), it is preferable to use figures for consistency and to allow for figures which contain things other than images.

Most packages have a COPYING file in the tree which explains the rules or the license used to be able to copy any parts of the package. There should also be a COPYING-DOCS file which will contain the FDL or other licenses the documenter and maintainer agrees on. An example file is found in Subversion in the module gnome-docu/gdp/ COPYING-DOCS which contains the GNU Free Documentation License. The COPYING-DOCS file should be placed in the same place the COPYING file is located or in the top level of the package tree. If you wish to use the GFDL, you must have this file in the top level of the package.

A new build system has been developed for GNOME 2.4. Each package will no longer be required to have its own copy of xmldocs.make and omf.make. Instead, the files are pulled from gnome-common whenever the package is built from Subversion.

To use the new system, in autogen.sh change the line that invokes gnome-autogen.sh from:

USE_GNOME2_MACROS=1 . gnome-autogen.sh
      

USE_GNOME2_MACROS=1 USE_COMMON_DOC_BUILD=yes . gnome-autogen.sh
      

In addition, xmldocs.make and omf.make need to be removed from packages that used previous versions of the build system.

In the docs directory, a Makefile.am then is required that calls them:

figdir = figures
docname = gnome-calculator
lang = C
omffile = gnome-calculator-C.omf
entities = legal.xml
include $(top_srcdir)/xmldocs.make
dist-hook: app-dist-hook
	

Typically the application manual and possibly additional help documents will be made available to the user under the Help menu at the top right of the application.

A macro is used in your menu definition to specify inclusion of the help item on the menu, as follows:

static GnomeUIInfo help_menu[] = {
	GNOMEUIINFO_HELP("gnome-calculator"),
	GNOMEUIINFO_MENU_ABOUT_ITEM(about_cb,NULL),
	GNOMEUIINFO_END
};

An example of adding a help button can be found in main.c of gfloppy in the gnome-utils package. It bascically requires connecting gnome_help_display to a button and testing for an error if the documentation is not found:

while ((button = gtk_dialog_run (GTK_DIALOG (toplevel))) >= 0) 
	GtkWidget *density_option;
	GtkWidget *dialog;

	if (button == GTK_RESPONSE_CLOSE) 
		break;

	if (button == GTK_RESPONSE_HELP) {
		GError *error;

		error = NULL;
		gnome_help_display ("gfloppy", NULL, &error);
		if (error) {
			GtkWidget *dialog;

			dialog = gtk_message_dialog_new (GTK_WINDOW (toplevel),
							 0,
							 GTK_MESSAGE_ERROR,
							 GTK_BUTTONS_CLOSE,
							 _("Could not display help for the "
							   "floppy formatter.\n"
							   "%s"),
							 error->message);
				g_signal_connect_swapped (dialog, "response",
						  G_CALLBACK (gtk_widget_destroy),
						  dialog);
			gtk_widget_show (dialog);
				g_error_free (error);
			}

	

The GDP team is a valuable resource for any documentation author. GDP members can answer most questions documentation authors have during the course of their work. It is also important to make sure you are not duplicating work of other GDP members by sending an email to <gnome-doc-list@gnome.org> and verify no one is working on the documentation for the application you are working on. It is also a good idea to send an email to the application's maintainer so the maintainer knows you want to work on the documentation for their program. The best way to get in touch with GDP members is on the #docs IRC channel at irc.gnome.org or else by emailing the http://mail.gnome.org/mailman/listinfo/gnome-doc-list/.

After an author has finished a document (or even a draft version of the document), it is a good idea to ask a member of the GDP team to read the document, checking it for grammar, proper DocBook markup, and clarity. One may typically find another author to do this by either asking on the #docs IRC channel at irc.gnome.org or by emailing the http://mail.gnome.org/mailman/listinfo/gnome-doc-list/.

Writing documentation typically involves a certain amount of interaction with the developers of GNOME or the application which is being documented. Often a document author will need to ask the developer technical questions during the course of writing a document. After the document is finished, it is a good idea to ask the developer to read the document to make sure it is technically correct. The documentation author should also make sure that the application author correctly binds and packages the documentation with the application.

When the document is finished, the document should be edited by another member of the GDP for spelling, clarity, and DocBook markup. It should also be read by the application author to make sure the document is technically accurate.

After the document has been edited and checked for technical accuracy, it is ready to be combined with the application or documentation package. This is typically done by passing the document to the application or package developer. In some cases, the documents can be committed directly into SVN, however this should only be done after obtaining permission to make SVN commits from the developer. Note that in many cases, the application may need to be modified to correctly link to the documentation. The packaging system (tarballs and binary packages) may also need to be modified to include the documentation in the package. Generally, this should be done by the developers.

The final step is to email the GNOME Translation Team at <gnome-i18n@gnome.org> to notify them that there is a new document for them to translate.

Maintaining a document is the final step in a document's lifecycle. Periodically the documentation you write needs to be reviewed and changed. This usually during a major release of the application you are documenting. You should look at the UI of the application and assess any changes to the UI the current documentation does not address. An equally important change you need to look for is any additional functionality added to the applications. You should also determine if any of the functionality already in the documentation has changed. A good place to look for changes in the application is the ChangeLog of the application. Even if you do not understand all the technical parts the ChangeLog will give you a good idea of the changes and additions to the application. You should not rely on the ChangeLog fully. You should have the most recent copy of the application before it is released to determine any changes or additions. Some of the changes can be subtle. Don't worry if you do not catch them all in the first revision of the documentation.

Since maintainance of the documentation is an ongoing process the original author might not choose to maintain the document. If you have written documentation for a GNOME application and do not wish to maintain contact the maintainer of the application and send an email to the gnome doc list <gnome-doc-list@gnome.org> stating you are not able to maintain the document. Either the maintainer of the application or the GDP will find someone else who is willing to maintain the documentation.