GDP Documentation Guidelines

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