Documentation Formats and Joomla
Historically we used to create our documentation using ‘Word Perfect’ but changed to using Microsoft Word, soon after Adobe ‘took over’ Word Perfect. This has served us well for many years, but unfortunately Word has not kept up with the changes in the Web and the need for short pages of documentation easily accessible by users. Yes, Word can generate HTML documents but anyone who has every looked at the created output will be struck by the obvious bloated code and its use of strangely named variables making it almost unreadable in its raw form. This necessitates a cleanup operation on the code before it can really be used.
So the search was on to see it there is anything ‘better’ out there.
The obvious candidate was something known as DocBook which is written in XML, which means that it can be created and edited by virtually any editor upon any platform. However to ensure good structure that meets the requirements of the DTD, something more robust is required. It also raises the question of how one retains the investment in existing documents and how one can convert them to the ‘new’ format. One advantage of the XML format is that it is reasonably easy to use XSL transforms to convert it to PDF, HTML or indeed many other formats.
Our investigation so far are as follows:
1. To convert Word documents into DocBook format a tool such as ‘Upcast’ is advisable. This is a reasonably good product and probably ideal for a large business, but for a small (one or two person) business will work out very expensive. There is an evaluation version available to test but has a feature that randomly changes characters in the generated output to ‘encourage’ one to purchase the full product. If there is only one or perhaps two short documents to convert this may not be a problem but when presented with many documents this is problem.
2. Once one has the XML document we need a good editor that understands the DocBook format. There appear to be three major players: a) Oxygen XML, b) XMLMind (also known as XXE) and c) Altova XMLSpy. Again none of these is cheap. There was at one time a free Personal edition of XXE available, prior to the current version (5.4) so it might be possible to locate a version on the web to use. All of the three offer evaluation editions (30 day) to try, but we are unsure exactly what happens after the 30 day period. Does it just cease to work?. Can a later evaluation version be installed? etc.
3. The final step is to convert the XML document into HTML for usage on the web site. Here we stumbled upon a little gem known as ‘DocImport’. This Joomla component is written by Nicholas K. Dionysopoulos the author of Akeeba Backup and Akeeba Admin Tools, which will be familiar to many. It is still in development so it only available on a git hub known as Assembla. It does however perform an extremely good job and we have successfully used it on our test sites without any major problems. So much so, that we are considering using it on our live site.
If your target is not a Joomla site then there are a wealth of XSLT transforms. There is a small blog that describes quite well how this is easily done, but it is not a path we have current cause to venture down.
This information may not be useful to all but for those going down a similar route they might find this saves them some time.