Best Practice: Managing versioned documentation in Confluence
Comment
Best Practice: Managing versioned documentation in Confluence
As a technical writer, I use Scroll Versions in my everyday work because it's a great tool. But at the same time, I leverage the dual benefits of dogfooding: It provides an opportunity both to improve the software and to develop best practices based on my own experience with the tool.
In this blog post, I would like to share my experience with you and describe our best practices.
As mentioned above, dogfooding has two major benefits:
- It helps you improve the software: When you put your product to practical use – to perform a concrete task – you will learn a huge amount about usability and related problems, and identify minor bugs and glitches.
- You can develop best practices: Dogfooding is also a great way to discover the best way to work with your software and make the most effective use of it.
Scroll Versions 2.2 – scheduled for release next week – will come with a wealth of improvements: changes, additions and enhancements that are directly attributable to the experience we have gained while employing Scroll Versions for our own internal purposes.
Right now, I’d like to describe the best practices we have developed for using Scroll Versions. So let's taker a closer look at how the tool is employed in-house at K15t Software.
Public Master Space or Private Master Space?
Before you start using Scroll Versions, you need to think about how best to set up your spaces. There are two different approaches to using Scroll Versions:
- A Public Master Space – Work in one space and publish to the same space.
- A Private Master Space – Work in one space and publish to another space.
Depending on the properties of your documentation, one or other of these approaches will make more sense:
- A Public Master Space is useful when you want to focus on managing multiple versions within one Confluence space.
- A Private Master Space is the best option when you have multiple products with similar documentation and wish to use the variant management feature.
Here at K15t we employ both approaches, because our offering largely consists of two product types with different characteristics – Scroll Versions and Scroll Exporters.
Public Master Space – The Scroll Versions space
We manage the documentation of Scroll Versions in the Scroll Versions space. This is managed as public master space: We publish the documentation of Scroll Versions in the same space (accessed via spacekey VSN) and mainly work with the version management functionality. With a public master space approach, all comments on pages are retained, and our users always have access to the latest documentation in the same space.
As we generally release a new patch version every two weeks, our dropdown list of working version would be extremely long if we created fresh documentation for every patch. That's why we only make brand new documentation versions for major and minor releases, and continue to work in the current version in the meantime.
When we release a new major version, we publish the previous version to a new space in order to archive the content.
Private Master Space – The Scroll Exporter space
Because all of our Scroll Exporters are based on the same source code and have much of the documentation in common, we have opted to manage all the exporters in a single space. This space is a private master space, which means that external users have no access to it. We utilize the version, variant and conditional-content functionality to manage and select content for the various Scroll Exporters.
For each Scroll Exporter we've defined a variant. We can apply attributes either to whole pages or to individual paragraphs that indicate whether that content is relevant for a variant. If we haven't applied any attribute, the content is automatically relevant for all variants.
When the documents for a specific version have been finalized, each variant – in other words, the documentation of each Scroll Exporter – is published to its own public documentation space.
That means the documentation for each product is made available to readers in its own dedicated space: The documentation of Scroll Office is available in the space accessed via spacekey OFCE, Scroll HTML Exporter in the space with spacekey HTML, and so forth.
Dining on our own dog food day by day is a great way to put our software to the acid test. When I talk to our software developers, I can put my finger on exactly where and how we can make Scroll Versions even more intuitive and user-friendly.
As mentioned above, the next release of Scroll Versions will offer a raft of improvements. So stay tuned, because Scroll Versions 2.2 is coming next week already.
Share Your Best Practices
Would you like to share how you use our add-ons to manage your documentation in Confluence? Please feel free to use the comment section below to tell our community how you exploit the benefits and make the most effective use of our add-ons.
Try Scroll Versions for free with a 30-day eval.
If you have any questions, don't hesitate to email us at info@k15t.com
