Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
Deleted user
Level
0 / 0 points
Next:
badges earned

Your Points Tracker
Challenges
Leaderboard
  • Global
  • Feed

Badge for your thoughts?

You're enrolled in our new beta rewards program. Join our group to get the inside scoop and share your feedback.

Join group
Recognition
Give the gift of kudos
You have 0 kudos available to give
Who do you want to recognize?
Why do you want to recognize them?
Kudos
Great job appreciating your peers!
Check back soon to give more kudos.

Past Kudos Given
No kudos given
You haven't given any kudos yet. Share the love above and you'll see it here.

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

Version controlled documentation

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

2 answers

1 vote
elizabeth_jones Community Leader Mar 10, 2021

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. 

1 vote
Thomas Bowskill Community Leader Mar 10, 2021

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

 

conflreqsver.png

Suggest an answer

Log in or Sign up to answer
DEPLOYMENT TYPE
CLOUD
PRODUCT PLAN
STANDARD
PERMISSIONS LEVEL
Site Admin
TAGS
Community showcase
Published in Confluence

⚡️NEW Group for Confluence Cloud Admins

Calling all Confluence Cloud Admins!  We created a new Community Group to support your unique needs as Confluence admins. This is a group where you can ask questions, access resou...

138 views 2 10
Read article

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