Why create documentation in Confluence

Whether your documentation (knowledge base) is good, ok or bad you might not get a lot of feedback.

But it matters. It might be a lot of work initially but a worthwhile investment longer term.

Why we use Confluence for our documentation

If you are already using Confluence, in this case it is hard to beat for documentation in Confluence. While you could create something with more design flare in WordPress, as a wiki Confluence has limitations that designers/marketing people find frustrating, longer term the key is not design flare, but it being detailed and up-to-date.

It is an ongoing challenge to keep documentation up-to-date. This is a team effort and everyone is already on Confluence, this makes a major difference and is the top reason we rejected the idea of using WordPress. In our experience the longer term quality is higher when writing technical documentation with Confluence. Customers and potential customers are happier which in the end is what matters.

Use a paid app for the 'backend'

You have to be careful about spending, but this one is worthwhile as documentation is one of the few ongoing touchpoints with customers.

For us, Scroll Viewport is a must have – it puts a ‘layer’ (for lack of a better term) on our public documentation that gives it a website look and feel. It takes a bit of time to learn, but it does a lot of little things that over time we have come to appreciate. For example, initially you are not thinking about a sitemap for search engines to crawl, but when you are it has you covered.

Another popular alternative is Refined.

Keeping documentation up-to-date

Acknowledge it is work, can be tricky and not a lot of fun to ‘clean’ up after the fact. The person who does it needs to be given the time and respect they deserve. In a large company it used to be a ‘let’s give it to the intern so we do not have to deal with it’ attitude. If you don’t know the product well, good luck.

The challenge of keeping Confluence pages up-to-date was a driver behind our creation of Space Content Manager. If you don’t bulk edit you can miss changes and even worse have contradictory information. We recently had a support request where someone complained that what we have in our documentation and on our site was different. The WordPress powered site was out of date.

Keeping pages up-to-date is a series of little things. Space Content Manager is a suite of tools to bulk edit Confluence pages across a space. It includes a find and replace, label manager, link manager and title prefix/suffix. We don’t pretend to have all of what is needed, even if we are adding more. We do know that few want to manage and pay for an app that does one small thing, even if it is useful.

If you are technical, think CQL

If you are more technical a catch all tool is Scriptrunner for Confluence. Needless to say creating and running scripts takes some time in addition to specific technical skill.

The largest challenge is often that the space administrator who is updating the documentation in Confluence often doesn’t have this level of technical skill. The more a system administrator has to be involved the more time and effort to update pages. The documentation stays out of date longer as a result.

 

Security

For those who get a lot of security pushback many new Confluence apps are build using Forge which offer data residency and add processing is done withing Confluence. Space Content Manager is built in Forge.

Request a Demo