Concluding on project documentation

After a few time spent on this subject and a few posts on this, I think I have reached the conclusion moment. Shortly, my goals were:

• to find a documentation format easy for writting and enough configurable as regards the generated output
• to allow different output formats
• light/easy/few tools required

I have taken into account the following formats:

• html
• docbook
• xdoc
• wiki

Some thoughts on each of them (thoughts that finally pushed me to the current solution):

• html way too related to output presentation
• xdoc quite powerfull and not very very linked to presentation. It misses a few things: imbricated section levels, meta support.
• docbook very powerfull, but way too complex (from both points of view: writting and configuration of output)
• wiki interesting, but the output is too limitted and requires a heavy solution (servlet container, except you are using the Wiki Plugin for Eclipse)

Conclusion:

An enhanced xdoc format (overpassing the missing features presented above) and a couple of XSLs to transform it either to a final document or to put it in the format of one of the other above mentioned formats.

Somebody could argue that I have tried to reinvent the wheel, but this is not the truth. I have added to the xdoc format just a few more things:

• level attribute for section element
• indefinite section recursion
• meta child element of properties element ... and that's all

I have already written 2 XSLs that transform it to HTML and Wiki and both are under 100 lines (even if I am not an expert of XSL). I will write another one that will transform my custom xdoc to Forrest xdoc and/or Maven xdoc and so I can use this format to generate a full site. Having only XML and XSL files I can work with aproximatively whatever editor in the world (for the moment I prefer using JEdit) and I can trigger the transformation process with a 10 lines Ant build script. In the next days I will start posting the custom xdoc DTD and an example, than the Wiki XSL (this is very intersting indeed) and the lite HTML transformer. If you are interested or you have other suggestions for me just drop me a line.