Best practice for doc updates

[Susan Lunn]

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.

[Anselmo]

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.

[Monika G]

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. 

[Kimmo Kyle]

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.