One of the things that every product needs, regardless of how simple it is to use, is good documentation. It’s not fun, it takes time, and isn’t technically intriguing. Regardless, it has to be done. The part that myself and team members have struggled with is a tool take makes it easy. We looked at a few commercial applications such as RoboHelp, but it always left me the impression we were rabbit hunting with a Barrett M107 .50 rifle. Our requirements were pretty simple:
- Easy to use
- Text based – This makes differentials and merging easy
- Reasonably priced
- Able to produce different types of documents (HTML, PDF, etc)
We finally settled on what is the best solution (not to mention, it’s open source and free) called DocBook. It’s based on XML, and does have a standard. XML is extremely flexible, and their output is generated by XSL transformations, so we can easily customize the output to meet our requirements. We started using the e-novative DocBook Environment, which gives you a simple command line environment for compiling your DocBook books. It too uses a GPL license, so you can customize it to your needs.
A simple book looks something like this:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "file:/c:/docbook/dtd/docbookx.dtd" [ <!ENTITY % global.entities SYSTEM "file:/c:/docbook/include/global.xml"> %global.entities; <!ENTITY % entities SYSTEM "entities.xml"> %entities; ] > <book lang="en"> <bookinfo> <title>My First Book</title> <pubdate>May, 2008</pubdate> <copyright> <year>2008</year> <holder>Kevin Jones</holder> </copyright> </bookinfo> <chapter> <title>My First Chapter</title> <sect1> <title>How to crash a .NET Application</title> <para>Call System.AppDomain.Unload(System.AppDomain.CurrentDomain)</para> </sect1> </chapter> </book>
Each book can be broken down into separate chapters, which are broken down into sections, then paragraphs. It takes care of some dirty work for you, such as maintaining a Table of Contents for you. It offers a lot of other standard features as well, embedding graphics, referencing other places in the document.
Since DocBook is capable of understanding external entities, I can place chapters, sections, any part of the document that I want into another file and create an <!ENTITY … > for it.
Compiling it is pretty easy. From the e-novative environment, just use the docbook_html.bat for docbook_pdf.bat to create your generated output, something like this:
> C:docbookbatdocbook_html.bat MyFirstBook
MyFirstBook is the name of the project in the projects folder, which is all automatically created for you by the docbook_create.bat script. Using the compiler, the out-of-box HTML template looks like this:
There you have it, a simple documentation tool. Not very pretty at the moment, but of course it’s easy enough to theme it to your company or product by changing the XSL.