How to write a manual for a GNOME application with DocBook

Manuel Rego Casasnovas

Some rights reserved. This document is distributed under the Creative Commons Attribution-ShareAlike 3.0 licence, available in http://creativecommons.org/licenses/by-sa/3.0/


Table of Contents

Introduction
Writing the manual
Style guide
DocBook
Templates
Compiling the manual
Install packages
Checking the result
Convert into different formats
Integrate as application help
Preparing the source code
Adding menu option
Opening help document
Translation
References

Abstract

This article is a guide about how to write help manuals for GNOME applications using DocBook as standard tool. This manual explains the right way to add a tutorial on a GNOME project, as well as the process to translate it. The integration process to add a new option in application menu that shows the help manual, is also explained in this article.

Introduction

A manual explains how to use a particular program. It is a very good method of transferring knowledge. Moreover, a tutorial is usually more interactive and specific than a book, and could be used as a part of learning. Besides, a manual is usually updated to the last versions of an application, while books are quickly old-fashioned.

So if you are a user of a GNOME application that do not have a manual right know, you can easily write it and integrate in the application following this guide.

In order to write the manual you will need to use DocBook, a markup language to write technical documentation. If you are a newbie on this kind of tools you could need more time to write the tutorial, anyway with this how-to you will be able to do it for yourself.

The last step will be integrate the written manual, as the application help, adding an option into program menu to show that help. For this process is needed to do some changes on the source code, but the whole process is documented with this guide.

Finally, this article gives an overview about how to translate a manual of a GNOME application written with DocBook, this translation it will be also integrated with the application.