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.

About these ads

5 Comments

Filed under personalog

5 responses to “Concluding on project documentation

  1. Anonymous

    I’m definately interested in what you come up with. I use forrest quite a bit for my open source project and one of my partners has been experimenting with Docbook for some architectural documentation. We haven’t integrated the two yet but we plan to.

    - Robert McIntosh
    robert.mcintosh@zurichna.com

  2. Anonymous

    For simple xdocs you can even use OpenOffice and edit it completely visually. At the end, just put the .swx file from OO in the content path for generation. Quite neat.

  3. Ralph Morrison

    Have you looked at DITA? It’s like DocBook but simpler. It can also be mapped to any arbitrary ML through the use of topic specialization and domain specialization.

    DITA toolkit including DTD and XSL to output HTML and PDF. http://www-106.ibm.com/developerworks/xml/library/x-dita6/x-dita_downloads.html

    DITA intro.
    http://www-106.ibm.com/developerworks/xml/library/x-dita1/index.html

    DITA spec.
    http://www.oasis-open.org/committees/download.php/12091/cd2.zip

    DITA coverpages. http://xml.coverpages.org/dita.html

    DITA intro series. http://www.arbortext.com/resources/xpn_jun_04.htm

    DITA marketing overview.
    http://www.idiominc.com/products/worldserver-DITA.asp

  4. Roman

    Hi,

    I just implemented a prototype of an documentation plattform based on Forrest (forrest.apache.org) and DITA. Since I don’t want to expose our documetation authors to the DITA format, we’ll be using the XMLMind XML Editor for the content creation part.
    The prototype works very well.

    best regards,
    Roman

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s