[infinispan-dev] Documentation versioning

[Pete Muir]

All,

We've had various bitty discussions about how to handle different versions of the documentation now that we've moved to Confluence.

We had a discussion on IRC, from which I wrote up the notes below. The short version is that for each minor version (x.y)  of Infinispan we will clone the Infinispan space. I would envisage this happening shortly after a release. 

The .org team will add a couple of plugins to Confluence to make this work nicely. The first is a plugin to actually clone the space. The second allows us to display spaces hierarchically, so that we can something like:

Infinispan:
 | - 4.0
 | - 4.1
 | - 4.2
 | - 5.0
 \ - HEAD

This means there is no need to indicate in the text the releases the page is relevant for. You may still wish to add a note (admonition) that the feature was introduced in a particular version to guide the reader. I will add an example of this to the style guide.

HTH

Pete

=========================================================

Use markup inline (feature available since XXX)
------------------------
- Fixes are very hard
- Will get messy quickly
- Error prone
- hard for use to read
+ No infrastructure needed

Conclusion: Not suitable, it's just too messy

Export to static format (PDF/HTML)
----------------------------------------------
+ Confluence / Scroll Wiki make this easy to achieve
- docs cannot then be fixed post release

Conclusion: Not suitable, lack of post release edit is a killer

Export to docbook
------------------------
+ Good idea in principle, as it allows us to use existing infra such as git to store docs from then on
- Requires two different approaches to edit docs depending on what version they work on, which is confusing for people
- current process is very manual (export manually, transform manually, add release info manually)
- requires "double qa" - we check all the docs on confluence to make sure they look nice and then have to do so again for the exported version

Conclusion: Not suitable, it's good idea, but current process is too manual, will re-evaluate when this is improved

Copy subtree of pages
------------------------------
+ Fit's structure well as it keeps everything within a space
+ Allows post release editing within confluence
- Plugin for this looks unsupported
- Would need to be configurable to rename pages and update all links including includes etc.

Conclusion: Not suitable, plugin isn't mature enough, otherwise a good approach

Copy space
---------------
+ Structure is fine
+ Allows post release editing within confluence
+ Plugin looks stable, no naming issues
+ This is the approach taken by others who use confluence for docs (including atlassian)

Conclusion: This looks like the best option open right now.