The Foundations of Good Documentation with K15t

The internet slang term RTFM suggests that a user should always refer to a product’s documentation before asking a support question. Excellent advice... but it requires the documentation to be easily accessible and good quality. 

We at BDQ take documentation seriously. From a consultancy project for a specific customer to a product release to a wider audience, we feel that a piece of work is not finished until it is clearly documented in an easily accessible fashion.

Past approaches and requirements

Over the years we, like many others, have approached the problem of public documentation in several ways.

At one time or another, we have used pages on the website, downloadable Word documents or PDFs, help files authored in tools like Help and Manual and public Spaces in Atlassian Confluence.

These options have their advantages and disadvantages, but we wanted to solve the following requirements:

• Be Agile

We embrace Agile in our development and testing process, but our previous documentation approaches did not support this particularly well.

In reality, writing the documentation was a follow-on, waterfall phase that happened towards the end of the project or release. We need a more agile approach, allowing us to change the documentation as the release progresses and then publish it in one go as the release progresses. 

We therefore needed the ability to edit documentation to add new content, revise or delete existing material across multiple pages, review it internally and then release the package of new documentation publicly in a single “drop”.

• Support multiple product versions simultaneously 

The products we are working on will have several releases over time as we develop our roadmap and respond to customer feedback. The solution we put in place must allow us to have older versions of the documentation available for customers on those previous versions. 

To support multiple versions of Atlassian’s products that have different APIs, we need to have multiple parallel versions of our apps. As far as possible, we keep the functionality between these parallel app versions the same, but it is possible that the API limitations may not allow this. We therefore will need to have documentation for each version. Maintaining this will require us to keep several similar pieces of similar content in step.

We did not want the solution to require us to have multiple copies of the documentation in different spaces. We have tried this approach before and found copying changes between spaces a bit of a chore and prone to mistakes. 

• Presentation is key

As any contestant on MasterChef knows, you can have great ingredients with the best of flavours, but lack of presentation can ruin a dish.

To make the experience of using the documentation better for our customers, our content must look great (good enough to eat?) and be easy to search.

• Long-term approach

We are developing several products, and we want all our documentation to be managed and delivered consistently, putting in place a firm foundation for the future. This will make it easier for our customers to find what they need, and it will be easier for us to maintain.

K15t

In the Atlassian Marketplace, there is one vendor synonymous with documentation - K15t. 

Based in Stuttgart, the company’s products are used by over 5000 organisations worldwide to manage their content and documentation in Confluence. The Scroll Apps series of products enables teams to author, manage, and deliver documentation and technical content while leveraging all the collaborative muscle of Confluence. It makes documentation an agile process that keeps pace with development and fast-changing products and services.

After talking with K15t, they offered us some expert advice about which of their products would meet our requirements and how best to configure them in Confluence to meet our requirements: Scroll Versions and Scroll Viewport.

Scroll Versions

Not to be confused with the page history functionality built into Confluence, which is limited to recording the changes of individual pages, Scroll Versions adds comprehensive versioning control to whole Spaces. This versioning functionality is like branches within source control. 

Using this app, we can: 

• Create named versions of the documentation. 
• Compare content between versions.
• Merge changes spanning multiple pages between versions.

These capabilities address our first two requirements, allowing us to work in an Agile way and managing multiple product versions.

Scroll Viewport

To address the other two requirements, K15t suggested that we use Scroll Viewport.

This app allows the publishing of content within Confluence to a beautifully themed Help Centre, which includes easily accessible search available from the home page and at the top of every page. 

This screen capture shows how contents in Confluence is displayed in Scroll Viewport: 

As we mentioned, presentation is key and the Help Centre Theme included in Scroll Viewport really looks great on every device - no more struggling on mobiles to see a desktop oriented page.

The theme is highly customizable, allowing us to brand the portal easily, but if required an entirely custom theme can be built using Velocity, HTML, CSS and Javascript.

While we did not need that option for our help centre, it is good to know that the option for a fully custom theme is available to us, if we wish to go in that direction in the future. 

When used in combination with Scroll Versions, Scroll Viewport is a powerful way to manage documentation and make it easily accessible to external users. Specific versions can marked as visible within the Viewport and they are then available to customers within the Help Centre from a version drop down menu.

Another useful feature of the app is that it allows Global URL Redirects to be configured. This allows us to set up short links to content within the help centre or anywhere on the web. Sorry bit.ly, we might not need you so much in the future. 

Our setup

The rest of this post delves a little more deeply into how we configured the two products and the process we will follow to release new versions of the documentation, but first, let us talk about hosting. 

Hosting

Until relatively recently, the availability of Atlassian Marketplace apps was higher on Server rather than Cloud and so when we initially set up our Atlassian installation, we hosted them ourselves using Server running on AWS EC2 instances. 

However, app availability on Cloud has significantly increased over time and, if we were setting up our installation for the first time now, we would definitely consider Cloud to be the better option in many ways. Hosting, updates and security are handled by Atlassian, leaving customers to concentrate on actually “using” the products. 

Fortunately for customers who wish to replicate our documentation set up on Cloud, K15t has embraced all hosting options and recently released Scroll Viewport for Cloud to very impressive customer reviews. Additionally, Scroll Documents provides versioning functionality on Cloud similar to Scroll Versions.  

Scroll Versions

Due to using Scroll Viewport, the Scroll Versions Publishing functionality is not required. Instead, we followed K15t’s Integrate with Scroll Versions documentation. Specifically, the integration allows to author new versions privately and make them publicly available in the Viewport at once.

As mentioned in our requirements, we must support two parallel versions of our  product to handle difference in the Atlassian API between version 3.x and 4.x of Jira Service Desk. 

In the version setup, we created an initial “First-Version". Off this, we created new versions called "3.0.0" and "4.0.0" and made them visible via the Viewport (see below for how that was configured). 

We then created two additional versions called "Next-REL3" and "Next-REL4". Documentation changes for later versions will be mostly made in "Next-REL3" and merged into "Next-REL4", with only "4.0.0" specific changes being made in that "branch".

This configuration looks like this in the app:

Creating new releases of documentation follows these steps: 

• Merge Next-REL3 with Next-REL4

  • Go to Space Tools > Scroll Add-ons

  • Select Scroll Versions > Versions

  • From the list of Versions select "Merge" from the Actions menu of Next-REL3.

  • Merge into Next-REL4.

• Rename Next-REL3 and Next-REL4 to the version number of the new releases

  • From the list of Versions select "Edit" from the Actions menu of the Next-RELx.

  • Change the name to the version number 3.x.y or 4.x.y

  • Change the colour and set the Release Date.

• Create new Next-RELx versions.

  • Press the "New version" button

  • Name the version Next-REL3 or Next-REL4.

  • Select the correct Preceding Version. 

  • Set the Color to gray. This represents that the version is not visible in the viewport.

• Stop edits in the new releases

  • To prevent edits we apply edit restrictions to a Confluence user group called bdq-none - a group contains no users. See How can I lock version editing after publish?

  • From the Action menu select "Manage restrictions".

  • Add the group "bdq-none".

  • Press the Save button. 

• Display the release versions in the Viewport

  • From the Actions menu select "Show in Scroll Viewport" next to the 3.x.y release.

  • Repeat for the other release 4.x.y.

• Verify that the documentation is visible via the Help Centre from an Incognito browser window. 

This diagrams shows how the versions described interrelate following the steps above:

Scroll Viewport

To support future apps, we have used the approach described in Structure Your Help Center to create a multi-space help centre. This requires setting up the following spaces. 

• Portal space

  • This root space contains no actual content and is used to put text on the help centre home page via an Excerpt macro on the space home page.

  • In the Scroll Viewport settings for this space, we set the viewport up as a “Viewport Collection”. This means that any viewports that have the same path are grouped together under the portal space. See Group Viewports in a Collection.

• Member space

  • One of these is created per product and contains the documentation for that product. 

  • The layout that we use for this space is the Detail layout and not the Hero layout. This is controlled by a setting called spaceHomePage.layout in the overall Help Center theme. The image used to represent the space in the theme is the Space logo. 

  • Call to Action Button at the top of the page is controlled by the Confluence label: scroll-help-centre-cta-page.

  • Pinned pages are selected using the labels scroll-help-center-pinned-page-1, scroll-help-center-pinned-page-2 and scroll-help-center-pinned-page-3. The text displayed on the Member Space page is by using an Excerpt macro.

  • News pages are selected using the label scroll-help-center-news-page. Up to three pages are displayed.

The relationships between the spaces are as follows:

In order for the documentation to be visible to non-logged-in users, the spaces must allow Anonymous access to view the pages only. 

Conclusion

Without any hesitation we would recommend both Scroll Versions and Scroll Viewport to anyone who wishes to manage anything other than the most simple public documentation within Confluence. They will be the foundation of RTFM-able documentation for us for the foreseeable future.