[infinispan-dev] Documentation versioning

[Mircea Markus]

On 1 Aug 2011, at 15:52, Pete Muir wrote:

> 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.
Nice!
so there'll be different links that point to the documentation root for each release? 
Also I guess that if we need to modify something in a prev version (e.g. a spelling error) we'll also have to change it all its successors? (similar to our git model..).
> 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.
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev