Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Best practice for doc updates

Hi all -- My company has an internal user guide on Confluence for users of our product that include many stakeholders. The guide information is written by the product owners.

Previously, they would write the information at the end of the release and update or create pages as needed, which was sub-optimal as it created a time crunch. Newest thinking is to go agile and have the information created within the guide during the sprints as the features are completed. 

But the internal user guide is live, which means that the newest information is about features not yet released. In some cases, the changes are made to already existing pages. 

I looked through the existing macros our company has (and they currently have a moratorium on 3rd party plugins) and was not able to see anything that the company currently has that would help.

Some thoughts I had on this was to:

  • Copy the parent page and child pages to a different space for users and overwriting when the product was released. But I would have to do each page individually, which is not optimal. And I don't think Confluence allows overwriting of pages, so it would need to be delete and recopy...
  • Export it to a PDF at the end of the release and send it to the interested stakeholder groups and let them post it to their groups. But we use the dropdown macro to make it easier to scan information, and using print would defeat the purpose. Also I have not used this feature of Confluence before, so I'm not sure how it would handle dropdowns. If anybody has, please let me know how well it works.
  • Include a table at the end of the page that has a listing of the releases and what changed during each. That way, if a user notices a discrepancy, he/she can look at the bottom of the page and notice that the feature is part of future release.

Any further thoughts would be greatly appreciated.


What I think Atlassian themselves does is they create a new space for each version of the software. This way they can keep updating the copy while developing, while the current is still the one live to the public.

Never done it this way myself as I don't have public docs in Confluence, but it might work.

My company uses a variety of different things for this. We store information in Confluence and Jira but also try to be flexible if there is a new need. 

For release documentation, we used to sit down with key teams (support, sales, etc) to discuss things that were being released the day of the release. That became cumbersome as teams grew and other teams also wanted access to the information. So, we swapped those meetings for a quick summary document/page. We list the release date, and then each PM and/or team can include information on what's going to be released on that date. They can include notes, screenshots, or simply just link to another Confluence page or Jira issue with details. The document is live all the time, so updates are seen instantly. But, since it has a release date on it, we minimize confusion. 

I wrote up a blog post on some other ideas around agile documentation recently if anyone's interested. :) Basically, we needed to adapt our documentation style depending on the story/feature and team. 

Hi Susan,
there may be a difference of best practice depending on a need to keep yesterday's newspaper directly accessible.

Concerning user documentation for internally used software, we are not much interested to offer outdated documentation. So if somebody wants to see an old status, he will need to stray through the version history of user documentation pages.

Actually we expect each page to be up-to-date at any time. Therefore we use page titles for activities which persist over long periods. Under such titles - usually starting with "How to <do>..." - everybody may update with his personal experience how to manage the named task. Screenshots and explanations complement each other. Both is necessary to feed the search adequately on the one hand (full text search) and to guide elaborated readers with the screenshots they might recognize quickly when scrolling through the page.

Of course users will experience, that some pages may not have been updated yet. In such cases we insist on either self-initiative in authoring outdated pages or to at least contact one of the authors either by mail or call or also by commenting at the bottom of the page. Usually the authors get a notification about changes or comments on pages they worked on. So a community of care-takers is formed.

And what happens to content nobody cares for anymore? Well, we estimate, that such pages are not even read or clicked on in the hit list of a search. So we ask for a tool to measure whether pages are actually used. Two indicators may help to analyze this: a) less than 5 times per year the page has been clicked anymore (this may vary with the number of users). b) if clicked, nobody stays on the page for more than a few seconds. So we expect, the content wasn't really catchy and therefore most likely not considered to be relevant. The number of seconds a user should spend on a page may vary with the number of words on such a page.

So far we miss such a tool for identifying pages, which have become uninteresting. So let's see, what will come up.


Log in or Sign up to comment
Community showcase
Published in Confluence

An update on Confluence Cloud customer feedback – June 2022

Hi everyone, We’re always looking at how to improve Confluence and customer feedback plays an important role in making sure we're investing in the areas that will bring the most value to the most c...

187 views 1 3
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