How do you update Confluence-based end user documentation at release time?

[Brandon Jackson]

This article:

https://confluence.atlassian.com/doc/develop-technical-documentation-in-confluence-226166494.html

Describes how to create a new page with a draft, review, publish workflow. How does this work in practice? Specifically, how are you 

1. Publishing all the new pages at the same time following a release?

2. How are you doing the same with page edits?

[Matt Reiner _K15t_]

Hi @Brandon Jackson 👋🏻,

I'm so glad you found this page in the Confluence documentation. That's where I first started learning how to do documentation in Confluence. There's more to it then is laid out here, as you've seen.

The place I'd start is by understanding the difference between page versions—which that Confluence documentation talks about—and "space versions", which is what you need for releases like you're talking about.

Page Versions

Each time you submit a change on a Confluence page, it creates a new version of that page. For each page, you can view the Page History to see all versions of that page and view the changes between each. This makes it possible for your team to see who made what changes to the page, and revert any changes if needed.

Space Versions

Page versions are very handy for viewing changes made to individual pages over time, but when writing documentation, it's important to also track and manage changes to entire collection of content; like a space.

For example: When product version 1.0 is released, your team will need to maintain the documentation for the released version 1.0 as well as create documentation for the upcoming product version 2.0 from the initial 1.0 documentation. Not to mention documentation for a bux fix in 1.1.

Teams need a way to manage changes to multiple pages within a space and control whether they are included in a larger version. This is especially useful when writing documentation for a product, which has new versions released over time.

There are a few different ways to manage changes to an entire space, depending on how your team writes your documentation:

Create a Space for Each Version
A great way to start managing space changes is by creating a space for each version of your documentation.

Write in an Authoring Space and Move for Publishing
If your team makes a product that's always on the latest version, like a SaaS app, it may be less important for your users to have access to older versions of your documentation.

Write in One Space Using Page Restrictions
Another approach would be to use a single space for both authoring new documentation and publishing released documentation. You can restrict new pages until they're ready for users.

Manage Multiple Versions in One Space With Scroll Versions
Expanding the functionality of page versions, the Scroll Versions app introduces the concept of true space versions. This marketplace app manages space versions automatically, so you can quickly publish all the changes at once when they're ready.

In regard to your question on a draft, review, publish workflow, there are two pretty good options in apps on the marketplace:

Simple Workflows

The first option is a simple "write, review, and publish" workflow, which is built into Scroll Versions itself. While you can't customize the phases in the process, it fits the needs of many teams who need to track what pages are being drafted, reviewed, and which are ready to be published. This workflow works well for small teams or teams where writing and review is done only within the group.

Comalla Workflows

For advanced workflows with multiple phases, approvers, and other automations, consider Comala Workflows. You can build very complicated processes involving multiple review phases and span multiple teams. This approach works well in cases where you are documenting a feature that first must have a technical review by an engineering team, a market copy review by a marketing team, and a liability review by a legal team. For each phase of the review, you can assign reviewers who must sign off before the documentation can move along in the process.

[Thomas Bowskill]

Hi @Brandon Jackson 

For my case: there are change requests in JIRA, that are linked to Confluence pages where the underlying documentation resides. The Change Advisory Board (CAB) process should include checks to make sure the documentation gets updated with each release. Changes are approved if they evidence the documentation has been updated -- that way documentation is simply part of the change process. Our JIRA tags the affected application, so I I wanted to know what has changed for an application, I would have a JIRA query and look at the linked Confluence docs.

Trouble is that, out-of-the-box is is relatively hard to track which page version corresponds to certain releases (as a workaround I add in table to my pages that  summarises the material revisions made). And the Draft ideas from the Atalssian link are good, but if you are updating a page to reflect a future release version you can't restrict the access as people will lose the ability to see the current version (and creating a copy of the page has its own downfalls, having to ensure people don't look at the wrong page / if you rename the link breaks, etc).

There are workflow tools like Commala that can put more process and governance around drafts and publishing, but I find the biggest issue out there is getting a culture in your organisation to continually update documentation and keep it current.

Not sure how much this helps you - hope I didn't totally miss your point :)