First of all, you should know that exists a GNOME Documentation Project managed by a team and with the support of the community. In its web page you can find a lot of links and information related with how to write documentation for any GNOME project, from developer documents to user manuals.
As any free software community you could be part of that team and contribute with your time documenting some GNOME applications, they will be glad about your collaboration.
Before start to write the manual you should read the style guidelines, in order to keep a common style appearance in all the documents related with the GNOME project. You can find this guide and many others at GNOME Documentation Library web page.
Anyway, just in case you can not read it, the next list tries to summarize the main advices extracted from the guide:
A good technical documentation has to be comprehensive, conformant, clear, consistent and concise.
There are four golden rules:
Limit each sentence to less than 25 words.
Limit each paragraph to one topic.
Provide instructions rather than descriptions.
Write in a neutral tone.
Use screenshots only when they are really needed.
Review the list of agreed terminology for use in GNOME documentation.
If you like that your work, the application help manual, to be included on future releases of that program, you should take care to follow the standards defined in the style guide. Otherwise, the application developers could not accept your collaboration, so this guide is very important and is highly recommended reading it.
In order to write a standard manual for a GNOME application you have to use DocBook. DocBook is a language for writing structured documents using XML, currently maintained by OASIS (Organization for the Advancement of Structured Information Standards) .
If you already know this system you can skip this section, anyway it includes only a few references about how to write documentation with DocBook.
Documents in DocBook are just simple XML files with some special tags, these tags define the structure of the document. The writer do not have to take care about the final appearance of the document, and he can be centered only on the content. This is the main advantage of this kind of systems to write documentation, like DocBook or LaTeX. Moreover the final result could be published in a lot of different formats (HTML, PDF, RTF, etc.)
You do not need any special editor to write a document in DocBook, just use your favorite text or XML editor. However, in order to generate the final document you need some tools that will be explained at the section called “Compiling the manual”.
There are a lot of references about DocBook on the web, but the most important are at the official website.
In the next list you can see the most common tags that you need to write an application manual for a GNOME application, from more to less used:
paraDefines a paragraph, almost every text in DocBook is enclosed in a paragraph.
titleTitle text of a section or other block elements.
sect1,
sect2,
sect3
These tags are used to define the document
sections. The top level sections are tagged with
sect1, subsections with
sect2 and
subsubsections with
sect3.
itemizedlist,
orderedlist,
variablelistDefine different kind of lists: a simple list, an ordered list or a definition list.
xrefInternal cross reference in the document.
ulinkExternal reference to any link outside the document.
caution,
important,
note,
tip,
warningSome types of messages set off from the text.
applicationTo mark a program name.
command,
option,
parameter,
replaceableThese tags define the name of an executable program with the different possible options and arguments.
screenshot,
mediaobject,
imageobject,
textobjectThese set of tags are used to add screenshots in the tutorial.
menuchoiceDefine the selections needed to be done from a menu.
guibutton,
guiicon,
guilabel,
guimenu,
guimenuitem,
guisubmenuTags to reference different things related with the Graphical User Interface (GUI) of the application.
keycap,
keysym,
keycomboDifferent tags to talk about keys on a keyboard.
Finally, DocBook allows to define entities in order to assign a name to some chunk of data. For example, these entities give the possibility to divide a document in different files.
You can define entities with something like the following line:
<!ENTITY app "<application>MY-GNOME-APPLICATION</application>">
GNOME manuals always define some entities that
you should use in your document, for example you could refer to the
application with &app;.
Other entities are already defined to use some special characters, for
example < for < or
& for &.
The GDP (GNOME Documentation Project) provides some DocBook templates to write GNOME tutorials, in order to avoid start a manual from an empty document. You can download these templates at GDP Document Templates or GNOME Doc Utils repository.
There are three available templates:
Applet Template: For GNOME applets (smaller applications).
Application Template: For GNOME applications.
Legal Info Template: A section with legal notes that is included by both templates above.
The next list enumerate some things that all the manuals should have, all of them are included in the standard templates:
Sections identifiers: All the sections of the document should have an unique identifier to allow cross-reference.
Authors names: The manual should contain information about all the authors that have worked on the document.
Copyright information: Documents should have a copyright notice and a license allowing free redistribution.
Revision history: Every manual should keep the history of all versions.
Application version: The tutorial should identify the application version for which the document is written.
Publisher name: All GNOME documents must include as publisher the GNOME Documentation Project.
Software license: The manual should include information about the software license.
Bug reporting: All documents should give a way for reporting bugs or comments about the documentation.
To sum up, the best way to write a good manual for a GNOME application is to use a template, as base document, and make all the needed modifications on the template.