Documentation HOWTO

1. Introduction
2. Documentation
3. User Interface
4. Bug And Wish Reports Management
5. Programming
6. Communication And Promotion

Writing documentation is a great way to start helping your application and the KDE project. If you decide to help out, your words will be translated to all languages covered by the KDE translations teams, and you will be helping thousands (millions?) to understand better their desktop and applications. Anyone with reasonable English skills and good knowledge of an application can help.

Modifying the documentation of an application involves: having your local KDE sources working folder, locating the files you want to work with, opening them, adding your improvements and sending the projects your modifications. To quickly learn how to do this, please check the Why Build and Maintain a KDE SVN Working Folder? guide.

Documenting an application involves help documents and context help. Context help is the quick pop up containing a short explanation you get when using the context help hotkey (usually Shift+F1) and clicking on a widget. This help is limited to the objective function of that widget, but it may be exactly what the user was needing to know, thus avoiding the need to open the full help system.

Help documents, (or an application manual, the set of help documents for an application), offer more comprehensive help about an application, and can include detailed information, examples, links to other documentation, information about menu commands, dialogs, screenshots, etc... Since the documentation is translated to many different languages, all the references in the help documents to screenshots, menu items, widgets or dialogs have to be translated in synchrony with the actual application and screenshots. To address this, the document format and tools used for help documents are designed for multi-lingual documents.

Context Help: Whatsthis

Context help is inseparable from the dialogs and widgets, as they are the target of the context help. In fact, in order to write context help, you have to touch programming or programming tools. Indeed, the context help is a property of widgets. In object oriented programming, a property can have different values, and behave differently depending on the value. In Qt/KDE programming, the name of the property is "whatsthis", and its value is the text the context help is going to display.

Fortunately, this task is usually not very difficult, as there are good tools to deal with user interface design, and better, you will use the knowledge acquired here later when dealing with user interface in general. Using the Qt framework (Qt is the base of KDE technology), it is possible to separate code and user interface. You have two basic cases here: the user interface is written with the general code of application (usually .cpp files) or in Qt Designer files (.ui files: it is a XML document). The second case is the best to start with, as it is simpler to work with. If you don't have Qt Designer installed, you can do so by installing the devel package of Qt from your distribution or the Qt Designer package (if your distribution has more fine grained packages).

Here you can find a detailed guide for writing whatsthis using Qt Designer and working directly with the source code: WhatsThis Tutorial, by Aaron J. Seigo.

Application Help Or Manuals

The KDE help system is based on the docbook format. This format and related tools make it easier to translate and to maintain the documentation for the whole project. The format was specifically designed by the OASIS group with technical documents in mind, and it is a XML based specification. The documentation for each module can be found in the doc folder.

Writing the documents in docbook format is highly recommended. But if you want, you can start improving the documentation now, and learn the docbook format later. but if you do so, please use text only format (ASCII). This way it will be easier for the documenters to transform it to docbook later.

Do not start from scratch if documentation for your application exist: try to improve it. Explain all commands, the main window organization, in sum, all aspects of the interface. A more complete list of what to write about is in the Questions You Should Answer When You Document KDE page, from the KDE Documentation Team Website.

Try to be user friendly, and try to write to the public of your application. Don't forget to proof your text for American English. You can find these tips and consistency rules in The KDE Style Guide. It is short, simple and obligatory. Its purpose is to maintain a uniform level of quality in the documentation.

For writing using the docbook format, the recommended place to start is the The Crash Course to Docbook. It will give you the basic knowledge to start. For more KDE specific stuff, please refer to The KDE Markup Guide to write your first document.

To help you in this process, you can use many tools. Kate is recommended for writing XML documents, and it is specially useful if you install the XML plug-in from the kdeaddons module. Don't forget to enable it after installing, by opening Kate, clicking the Settings menu, and the in the Configure Kate... menu item. Click the application/plugins icon inside the left side tree view, and check the Kate XML Completion and Kate XML Validation boxes. Now you will be able to see the XML menu when using Kate. If you are editing a docbook document, click the XML menu, then assign meta DTD and selecting the KDE docbook DTD, and you will transform Kate in a powerful docbook editor.

[ Edit ]