B.2. Introduction

One of the main advantages of DocBook is that there is complete separation between the content and presentation. DocBook is a pure XML format, and is well documented. It is believed that only a very small subset of its features will be required in order to achieve much higher quality documentation for DHIS. There are some 400 separate mark-up elements that cater to almost any level of technical documentation needs, but in reality, only a few dozen of these element will probably need to be employed to achieve high-quality documentation for DHIS 2, both for printed as well as online formats such as HTML or integrated help systems within the application itself. Therefore, there are wide range of possibilities in terms of which editor can be used for the creation of DocBook files. A fairly complete list of possibilities is located here. It is currently recommended to use Syntext Serna Free for editing DocBook source files as WYSIWYG. It is not recommended to use the editor XMLmind XML Editor Personal Edition (also known as XXE Personal), as the editor "silently" places unneeded whitspace and other ornamentation to the DocBook source which makes collaborative editing of documents very difficult.

One of the key concepts to keep in mind when authoring documentation in DocBook, or other presentation neutral formats, is that the content of the document should be considered in the first instance. The presentation of the document will take place in a separate step, where it will be rendered into different formats, such as HTML and PDF. It is therefore important that the document is will organised and structured, with appropriate DocBook tags and structural elements being considered.

It is good practise to break your document in to various sections using the "sect", or section element. Section elements can also be nested within each other, such as "Section 1" and "Section 2". This concept is essentially the same as Microsoft Word™ or other word processing programs. DocBook will automatically take care of numbering the sections for you when the document is produced. Two other important elements are the "itemizedlist" and "numberedlist". These are quite similar, but an itemised list corresponds to a bulleted list, which a numbered list will be rendered with each element being numbered sequentially. Other key elements are "screenshot" and "table" which should be self-explanatory.