versioned software, How to document in Confluence
Asked by Henning R?igaard:

I work for a software company whose main product at any one time exists in 4 versions, each version a further evolution of the previous one, adding, removing or altering features.  
This, among other things, present us with a challenge when documenting the product, and I am currently trying to figure out if Confluence is technically adequate to solve the challenge.

I would like to hear your take on the problem. How would you structure this kind of documentation?

I see the following options:

1) Create a space for each version. Whenever a new version is required, a copy is made of the previous.  
This has the advantage of nicely encapsulating everything belonging to one version, and allowing for easy access-control and deletion upon obsoletion.  
Drawbacks:   
\* No reuse of unchanged pages and such.   
\* Copying of spaces is, as far as I know not supported out-of-the box, but there exists hacks wich makes it possible.  
\* Checking for changes between versions requires you to browse far away (could be fixed by manually adding links i guess, however the should manually be deleted when linked versions are obsoleted).

2) Same as (1) but using Page hierachis instead of spaces. Each root page defining a version.  
This solution is much the same as (1), except copying of Page hierachies is supported.

3) Using multiple sibling pages, one for each version. Whenever a new version is required, a new copy is made of the previous and added to the same parent.  
This has the advantage of placing different versions close to one another, making it easy to detect differences.  
Drawbacks:   
\* No reuse of unchanged pages and such.  
\* Difficult to administer when creating a new version: Each page must be copied seperately.  
\* Difficult to remove obsoleted versions: Each page must be removed seperately.

4) Using one page for all versions. Each page is segmentet into versions (collapsible regions?)  
I can really find any reason for doing this ... just wanted to mention that the subject had been touched.

We dont really find any of the above options to be very good.  
Ideally We would very much like a kind of In-Page versioning, much like books-online, where you switch between .NET og Sql Server version by selecting the version from a drop-down on the page.  
It would be nice of some of the page-content could be reused in some versions, e.g. 10 line description which is the same for versions A,B, and C but not D.   
Creation and deletion of versions should be relativer simple operations (like copying or deleting an entire page).


Answers:
author: Henning R?igaard
body: It appears that Confluence itself has the same issue with multiple versions of the same software. They use a space per version (solution (1)) and create new versions by using a hack (<https://confluence.atlassian.com/display/CONFKB/Copy+or+Rename+a+Space+in+Confluence>) for copying the space (manipulate backup xml). Kind of ironic that they dont officially support their own method of versioning documentation :)

We will go with the same method, but have found that is has some serious limitations: 3rd party plugins might not function as expected after restoring.  
More specifically we have used Gliffy for graphics and in-graphic links. When using the backup-restore hack for copying the space, in-graphic links will target the old space ...  
I do not blame Gliffy for not complying with an unofficial hack :), but be aware that other 3rd party plugins might also experience problems.

Methods (2) and (3) kind of fell to the ground when we realised that confluence uses the page title as a key (...) for the page, e.g. it is part of links and must be unique within a space.


author: Henning R?igaard
body: Yes, we are also using JIRA, although currently only as a tracker for assignments, not for documentation. How would you use it for documentation?


author: Chung Park Chan
body: Are you using JIRA as well? I had a suggestion if you are using JIRA.


Tags: documentation

jira-software

version