The approach of writing documentation in HTML was inheretly problem infested. The content was "polluted" with HTML presentational tags and such impossible to convert to any other view. Another big issue was L&F consistency. Despite the explicit instruction of which HTML tags to use, authors couldn't keep up with all complexities and issue faced when writing HTML documents. Documents were also hard to shuffle around in a document book thus leading to a very big maintance costs

After some considerate time spent looking around, we came to the conclusion that Docbook initiative is the most reasonable way to go. DocBook is a XML/SGML DTD that lets authors in technical groups concentrate on the organization and meaning of the documents they write.

Docbook XML DTD ,which we are using, has accompanying XSL stylesheets that allow us to define different views of Docbook-ed XML content i.e., all the presentation issues are solved through XSL stylesheets. These stylesheets are very flexible, well maintained, and allow easily customized hooks for specialized home-brewed styles of views.

Simply put, you have xml tagged content, detached from any fomatting issues, chunked into logical pieces, which are then easily (re)arranged, put together, and in the end XSL stylesheet is applied against it to create any kind of presentational view.

Docbook DTD's are maintained by independent consortium - OASIS . The principal maintainer of Docbook is Norman Walsh , a member of XSL working group, Sun Microsystems employee.

Although Docbook DTD is very big, 300 + elements, the learning curve is very steep, and most of the time not more than 50 elements are used. This article is suitable for a first contact with Docbook. A good reference that you might want to use can be found here . There is also a very brief introduction with references to tools such as Emacs with PSGML.

Docbook documentation guidelines.