Introduction

For developers, writing user documentation is always a hassle. After spending weeks or months of coding, testing and debugging, they have to start again from scratch and re-write their work in a form that is understandable and useful to humans.

Decisions have to be made about what details are worth mentioning without being overwhelming, what should simply be dropped for the sake of brevity, and what prior knowledge or experience the reader would have. The documentation should be precise and concise, yet cover a wide range of aspects in order to answer as many potential questions as possible, and at the same time stay simple and comprehensible.

In addition to making choices on the content, the form of presentation needs to be considered. Should the documentation be published as a book or as a web page? As a simple README text file which is distributed with the code, or as a manpage? Should it be published in a WIKI? Or perhaps in all of those forms to distribute the documentation to as wide an audience as possible?

Although everybody would agree that content is much more important than format, developers tend to visualize a certain format before they even start writing the first words. It is understandable, as the format supplies a certain structure, and programmers love structure. Format and structure is what they do. Writing essays or prose is not.

Apart from the obvious problem of content being dictated by format, especially in big open-source community projects such as Adempiere it can happen that each individual piece of documentation will have a different look and structure, and the reader will miss a coherent theme underlying various subprojects.

As time passes, code develops and matures, bugs are fixed, functionality is added or dropped, and the user documentation constantly needs to be updated and adjusted. Having published in different formats, it means that a new edition of the PDF book needs to be issued, web pages re-written, and WIKI-pages updated. It is only a question of time until the various documents become unsynchronized, among each other as well as with the actual source.

Such problems are of course not specific to Adempiere, and already in 1991 HaL Computer Systems and O’Reilly & Associates jointly developed DocBook as a tool to write technical documentation in presentation-neutral form. This does not take the burden of writing the actual documentation off the developer, but it helps to solve most other problems.

In version 5.0, DocBook has undergone some major structural changes, so it is now commonly referred to as DocBook 5 to distinguish it from earlier versions.

A DocBook source document is a simple XML file which does not describe what its content should look like, but what the meaning of the content is.

The developer can therefore fully concentrate on writing the documentation content. He can mark certain lines as program code or screen shot, others as product or company name, and totally ignore in what font or color or size they should appear.

Writing in XML code means any text editor or word processor can be used, but of course XML-aware editors are a great help. In fact, this documentation is written using the Eclipse IDE.

After the document is written, XSL stylesheets are used to transform the XML source file into a variety of different formats. Thus a single source file can be used for generating PDF, HTML, WIKI, or even plain text results. If the documentation needs to be changed, only one file needs to be edited, and then all output formats can simply be re-compiled.

The stylesheets define where, if at all, certain blocks of text should be placed on a page, and what formatting should be used (font, color, background, size, etc.). Using the same stylesheets for documenting different projects results in a homogeneous presentation which the reader can easily recognize and feel comfortable with.

Adempiere's docbook subproject provides the stylesheets for publishing Adempiere PDF, HTML and WIKI documentation, and integrates the tools required to automatically generate them when the main code is being compiled.