[infinispan-dev] Documentation versioning

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.