This article was created in cooperation with Mike Rink – Product Evangelist at ComalaTech. We have covered the main challenges one faces in the process of creating and updating the Knowledge Base and also have provided solutions for them.
One of the most common uses for Atlassian’s Confluence software is building and maintaining a Knowledge Base (KB). However, challenges arise when it is time for a team to collaborate on updates to their KB articles. Not only does it take time to generate the content for the update, but also Confluence drafts are limited in that they don’t support space-to-space publishing, making it more difficult to post content publicly. Most users spend time creating the content, copying it to a draft page, and then once the draft is ready, copying it again and pasting their content to the published KB space. There is a number of problems with this approach:
Procrastination when it comes to documentation creation in the first place and its updating later on
The process of creating qualitative user guides is believed to be quite time-consuming. Indeed, complicated workflows which consist of a large number of steps seem to be a real disaster for the Subject Matter Experts. To document them, you need to spend hours writing detailed descriptions. It is so easy to get lost or miss an essential step. In a modern workplace, employees rarely have time to waste, which is why most of the teams tend to procrastinate the process of creating and updating the knowledge base.
Users lose their focus and productivity if they are forced to frequently switch between tools
Normally when creating a detailed user guide you need to capture a set of screenshots for every product feature, paste them to Confluence, and add descriptions to each of them. Even though Confluence provides a default how-to article template which can be used for step-by-step creating, a user still needs to invest considerable amount of time switching between tools to produce the guide.
Higher likelihood of errors when copying and pasting
When there is a need to copy content from the draft space to the public space there is a high possibility that some imperfections in the final version of the document will appear. For example, some parts of the text might be missed when copying, or it might cause some changes in document formatting.
It takes extra time moving all the content from one space to another
Why ask employees to spend time copy and pasting when they could be doing higher value work during their day? Every minute in the modern world counts, so each extra step in a workflow is not appreciated.
How Users Typically Post to Public Knowledge Bases
Imagine this scenario: a software company operates a public facing Knowledge Base administered by a Marketing Coordinator. The Product Manager informs the team that a product update requiring new content for the KB is coming; the software now offers in-app purchases. Obviously it’s important that the user base has resources to learn how to use this new feature, and so a tutorial must be created.
First of all, the Product Manager has to take the time to document the new process, painstakingly taking screenshots and writing descriptions for each step of the in-app purchase. This tutorial content is shared with the Technical Writer, who makes their additions and edits in the draft page. Once the new tutorial is approved the Marketing Coordinator has to copy and paste all the text and images into the public-facing KB space. Finally, the content is available for the public, but only after an extremely time consuming and error-fraught process.
There is a Better Way
Using Stepshot for Confluence and Comala Publishing, it’s quick and easy to manage the update process of an existing Knowledge Base. StepShot for Confluence is a software documentation tool for creating IT documents describing software-based procedures. As a Confluence add-on, the software enables users to create documentation almost within the knowledge base platform and after publish it back to Confluence. Meanwhile, Comala Publishing allows you to sync two separate Confluence spaces – one for your draft content, and one public space for your published content. By separating your draft and published spaces, it’s simple to collaborate on content for KB articles internally before they are shared with the public.
So, how can this team use StepShot for Confluence and Comala Publishing to update their KB instead? It starts with creating a new StepShot page in Confluence, which launches the StepShot application in the background. Then the Product Manager goes through the workflow in their app while StepShot creates a screenshot and text instruction on every click. Once it’s done, the Product Manager has the option to edit all of the captured images and text, after which the newly created guide is saved back to Confluence.
Once the Product Manager has completed the new user guide with StepShot, they can place it in the draft Confluence KB article. There, the Technical Writer is able to review the new guide and edit the article as necessary. Once they are happy with the content, and the Product Manager has signed off, they alert the Marketing Coordinator that the article is ready for the public.
At just the touch of a button, the Coordinator uses Comala Publishing to sync the article with the public page, updating the content instantly. Now users are able to view the new guide, and the KB is up to date.
It’s as easy as that. The process of creating and updating the Knowledge Base on Confluence may be a daunting task, but with StepShot for Confluence and Comala Publishing, users have a solution that makes it less painful.