Managing controlled documents such as software specifications, plans, or collaboratively-edited contracts isn’t easy at the best of times. And it’s harder yet if multiple stakeholders from different organizations are involved: project managers, engineers, QA, legal, etc. And if you’re still doing it the old-fashioned way – emailing Word documents around – it can be a nightmare. Each contribution needs to be merged, and changes have to be tracked manually in a revision history table which grows ever longer as the process drags on.
Thankfully, there is a better way. You can remove all the pain of controlled document management with the Atlassian Confluence collaboration platform. It enables you to have one single source of truth for all of your content – even for projects that require a full audit trail and document versioning.
In this blog post, you'll learn how the Scroll Versions Add-on for Confluence takes document versioning to the next level.
Atlassian Confluence is a great tool for creating specifications, guidelines, and many other kinds of documentation. When controlled documents are a requirement, there are multiple approaches to managing them in Confluence. The Radbee Blog outlines two methods, based on Comala Workflows and the Metadata Plug-in respectively. However, both these solutions lean heavily towards the technical side. In contrast, the Scroll Versions Add-on, while packed with versatile functionality, offers a more user-friendly way to extend Confluence's built-in page versioning and content management features.
Setup for Document Control in Confluence
Let’s say we're working on a specifications document for a custom software solution for a client. This type of document is typically modified constantly throughout all phases of a project. After acquiring stakeholder input, there will be at least one extensive request for comments. Extensions and modifications might be added after reaching each project milestone, and minor corrections to the content should always be possible.
In our scenario, all contributors/stakeholders have access to Confluence and work collaboratively on the specifications document. Each chapter corresponds to a Confluence page. Released versions of the specification (e.g. version 1.0, 2.0, or 2.1) are exported to a styled PDF, to be printed out the old-fashioned (lawyer-friendly) way.
If some stakeholders do not have the ability to access the Confluence single source of truth, Scroll Office provides functionality to export relevant chapters to Word, including in-style formatting. In combination with Confluence's Word import feature, this allows you to fully integrate Word into your Confluence workflow.
The Scroll Versions Approach
Scroll Versions' extended versioning functionality applies on a space-wide basis. Each versioned document should be managed within its own space. Using a distinct space for each document also enables easy management of permissions and restrictions.
Scroll Versions allows you to maintain concurrent versions of any page within a Confluence space. For example, you can have version 1.0 and version 2.0 of the "Technical Requirements" chapter available at the same time, corresponding to the overall document's versions. Earlier page versions are still available, and they can be locked to prevent edits.
The space's Document Admin adds and manages versions. He or she ensures that versions, both major and minor, are structured consistently. Doc-Admins can also activate the add-on's workflow functionality to benefit from preset states and roles. If the Scroll Versions workflow module is enabled, authors can draft content on Confluence pages, then submit it for review by authorized stakeholders.
Edit permissions can be defined individually for each version. This keeps archived or finalized page versions from being edited accidentally. Furthermore, versions can also be hidden entirely, if for example if you want contributors to see only the latest working drafts. Additionally, obsolete versions can be archived as read-only. All versions and page revisions remain available for a full audit trail at all times.
Eight Steps to a Versioned and Controlled Document
Let’s see how to get Scroll Versions up and running:
- As a Confluence admin, install the Scroll Versions add-on from the Atlassian Marketplace, and create a new Confluence space.
- Before you start collaborating on new content or revisions, you may want to import Word documents with existing content.
- Set up Scroll Versions in your Confluence space by defining at least one initial version (typically 1.0), and set permissions for Authors, Reviewers and Doc-Admins.
- If you also want to benefit from page states (Draft, In Review, Approved), enable the workflow feature.
- Now your users can collaborate on content in all relevant versions, based on the permissions you’ve defined for each version. If you're also using the workflow functionality, reviewers can approve or reject page drafts in any version available to them.
- After a release version has been finalized, publish the version to a PDF or Word file. You can also publish it to another Confluence space, e.g. for archiving purposes, with just a few clicks.
- To keep everything clean and tidy, you may want to restrict editing for released versions of your content, to make sure no one changes versions that have already been published.
- If it's time for another iteration, as a Doc-Admin, just create a new version of your space, and start the process over again.
The Goal: Full Transparency in the Document Creation Process
This method necessitates some tweaks to the traditional document creation process, and to its output. The game changer is to view the output document as the final result rather than as a working copy. The full audit trail implemented within Confluence allows everyone involved (including auditors) to compare the document’s versions and track down every single page edit. Gone is the process of tracking changes in revision history tables within the document – though if you want a revision history table included, you could easily maintain one in another Confluence page.
Tracking content creation and collaboration within Confluence fosters transparency in a way that isn't possible with distributed Word documents and manual revision. However you manage controlled documents in Confluence, it's an exceptional tool not only for managing specifications, but also for many other purposes such as software documentation, knowledge bases, and more.
With K15t Software’s Scroll Add-ons for Confluence and the content management features of Scroll Versions we've seen in this blog post, you can collaborate on content in an efficient and painless way. If you have ideas or questions, leave a comment below or send us a message – we're here to help!