January 2007

Using AurigaDoc for simple documentation projects

Several projects I worked on recently for a small financial solutions provider involved creating small utility programs in the Providex programming language. One of the requirements was to create end user documentation for these applications. We wanted to be able to produce both printed documentation and HTML help from a single source document. We also needed to document some internal business processes.

We did some research and ultimately bought a shrink wrapped software package from ComponentOne called Doc-To-Help. The idea behind Doc-To-Help is that you can use Microsoft Office Word to produce documentation for multiple target formats from a single source document.

Doc-To-Help is a vast product with many features. I managed to produce the required documentation using Doc-To-Help and Word. It took a great deal of tinkering and reading documentation to get the results we wanted. I have to say that ease of use was not one of Doc-To-Help's strengths.

One of the fundamental weaknesses of Doc-To-Help is the fact that your source documents are "Word" documents. The current trend in documentation seems to be XML. XML is an open standard, and with XML source documents, you have a range of choices for tools to work with.

DITA and Docbook are XML-based documentation architectures. Dita has it's origins at IBM before becoming an OASIS standard for documentation. Docbook has a large and robust XML schema for production of various documents. Both are open standards for documentation production. Support for these two standards are appearing in numerous commercial tools.

AurigaDoc is a java-xml-xsl based documentation tool for writing xml documents and converting them to other open formats like HTML(single and multi page), DHTML, PDF, PostScript, Formatting Object(FO), RTF, Java Help and HTML Help(.chm). AurigaDoc is open source software.

AurigaDoc source documents use a subset of well formed html tags. This reduces the learning curve and makes its easy for people already knowing html to write documents in AurigaDoc format. The presentation of output documents can be controlled with CSS style sheets. You can run Aurigadoc from a command line or it can be integrated into Java applications.

AurigaDoc is a tool to consider for your simple documentation projects. The tool has a fairly short learning curve because the source documents use familiar HTML tags. Output docs can be formatted, to a limited extent, using a CSS style sheet. For documenting simple vertical market applications or internal processes, this is a tool that you may want to consider.