[infinispan-dev] Documentation versioning

[Pete Muir]

On 1 Aug 2011, at 16:06, Mircea Markus wrote:

> 
> 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? 

Yes. We will add a page for Documentation on jboss.org/infinispan (rather than a direct link to Confluence). This will list out the major versions of Infinispan (starting with 5.0 as we don't really have any proper way of going back in time with this model), and link to the relevant confluence space. We will also have some sort of index in confluence, but I'm still sorting out with the .org team what that looks like.

> 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..).

Right. The only disadvantage with confluence is that you will need to do this manually, as confluence doesn't support patches... So basically, keep fixes to old versions to a minimum and concentrate on new versions.

>> 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
> 
> 
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev