It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

versioned software, How to document in Confluence

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

3 answers

1 accepted

0 votes
Answer accepted

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

0 votes

Are you using JIRA as well? I had a suggestion if you are using JIRA.

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

Suggest an answer

Log in or Sign up to answer
Community showcase
Posted in Confluence

Lessons and Learnings: Six Months of Working Remote [Discussion]

Hey there, folks! For most of us, the past six months- yes, you read that right- have been a journey. More people than ever before have pivoted to working remotely, and navigating being on-scre...

5,343 views 4 6
Join discussion

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you