Writing user guides with Confluence might be a bit painful because the tool lacks for version control management: there is no way for instance to tag the status of a page with a given version.

Here is a common use case: let’s say that you have a library and you want to write a developer guide and a user guide about it. If your library evolves, new functionnalities will arise of course. The thing is you want to be able to retrieve the documentation related to a given release of your library but you want also that your Confluence web site refers to the latest version of the documentation.

A good solution for this use case is to store your documentation in your version control system (CVS, Subversion, whatever). The document needs to be stored in text in order to use the functionnalities of a version control system (diff, merge, etc). 2 major solutions come in (my) mind:

  • Docbook: really nice and generates very professional output
  • A wiki markup Confluence page

Then, every time you deploy the maven web site, you want the documentation to be updated on Confluence as well.

Remember my maven confluence plugin? I will update it soon to implement this use case.

Stay tuned!