James Little

I’d love to see some! I was reading an ex-colleagues blog (Big Geek Consulting) which presents some tools for building useful documentation.

Big Geek’s list is a collection of tools included in a Slashdot discussion:

• FOP is an Apache XML XSL-FO renderer, written in Java. So it doesn’t really address the documentation issue, Apache FOP only provides a rendering solution.
• Xetex is a latex descendant. TeX solutions do not solve technical documentation issues, but I believe text based solutions like LaTeX do provide better version tracking opportunities that a binary formatted document.
• Lout Vaguely wiki like (but pre-dating) style of document writing, but with support for all the bits you need to create a document, not just text. Uses Knuth algorithms for line spacing. Lout is a document formatting system designed and implemented by Jeffrey Kingston at the Basser Department of Computer Science, University of Sydney, Australia.
• Prince An HTML based commercial solution for making real documents. It supports new and fancy CSS properties that let you make real documents. Mergable, diffable, standards based, but not free.

I think DocBook should also be added to the list; DocBook is an Oasis supported XML standard for xml technical documentation, used by CERN, FreeBSD, Linux, Gnome and co. From which you can use XSL-FO (or FOP) to render into whatever pretty format you want.

Purposefully excluded from the list:

• OpenOffice
• MS Word

Both of these applications now support XML based document formating. I think this makes both applications acceptable technical documentation options, as long as Open XML standards are used, then real difference comparisons could be made between versions.

My issue with technical and project documentation is that it does not represent a dynamic system well. Typically business users and management will want to use Microsoft word products and turn on change tracking to manage change. The problem I have with this approach is it is almost impossible to understand a document that has change on; it is impossible to compare different versions of that document and the document grows to incredible size to manage it.

A XML or other plain text markup solution offers simplicity in change management, it can be delegated to a content management system with difference tools – like subversion or CVS, where most of the project deliverables are maintained. Where such a solution would fail would be with business users , or anybody who wants to create a document quickly.

For me, this would make OpenOffice or Microsoft word (if users saved files as XML) the best solutions. The user would be able to quickly create XML based documents that are easy to read and anybody who wanted to compare any particular version would be able to do so from the source management system.