Version controlled documentation

Question

Hi - I have been trying to replace our customer-specific configuration docs, which we used to produce in MS Word, with a set of Confluence pages.  We are then using Scroll Documents PDF Exporter to produce a great looking PDF.

The trouble with this is that our customers would like to track changes and comment on the versions, and Scroll PDF Exporter cannot produce a version that shows the changes between versions.

The other issue is that we embed Jira macros in the document and so we would not track changes in these (but that may not be so much of an issue).

It feels like this should be something we could do in Confluence.

Has anyone built a Confluence solution like this, and if so could you share your approach and the steps you went through?

Thanks to anyone that has time to reply !

Simon

Thomas Bowskill · Answer

Hi @Simon Teppett

I use a lot of version control tables within my documentation (I'm a BA, so a large portion of my life is spent documenting things), and I've personally found that doing things manually often gets the best result.

The problem I found with the Confluence version changes is that it's tricky to tell the difference between major and minor versions. The compare functionality is really cool, but often you need to compare two particular states in the document with each other, but it's unclear sometimes which versions are best compared.

Each bit of documentation works differently, so the way I do things may not map across to what you do; on the off-chance it does, here is a common way I manage requirements (which may translate to individual configurations in your documentation:

* Each requirement sits in a table. The table (manually) tracks the "Documentation version" as a column
* The document itself has a version control table, where I manually add version numbers and summarise what essence of what has changed

e.g. if I have a requirement "BR01" that is in a "V1.0" "Only allow red velvet cakes", but later down the line in documentation version 1.5 this requirement gets reworked to be "Allow red velvet cakes and Victoria sponges", then I'll reflect the documentation version as "V1.5" and also update the main documentation version control.

The con of my approach is that this is manual, it takes more time and has nothing to do with the confluence versions, but that's also the pro of the approach -- being a bit more hands-on with version control and changes makes it far more readable to the end user (and people have to consciously think about what changes they make). They see a table of requirements and instantly know "on I am on version 1.16 and I can see this requirement hasn't changed since 1.2". Very rarely do I find that people want to specifically see the exact changes that were made -- they often want to know the crux of what has changed. I've redacted an example of the typical way I manage my manual versioning tables (and remember, each requirement I have also points to which version of the document it was updated in).

Hope this helps you

elizabeth_jones · Answer

Hi There!  We use confluence for all of our documentation and version control is built in. I like that there is a macro that shows the version history so that you can easily click through and see past comments and changes. The ability to embed jira macros and the direct connection between the tools is a great help. You can then export via word or .pdf the version of your choosing. Let me know if there are any other questions that I can answer.