Brainstorming our documentation strategy at Write the Docs Prague

Catherine Heath | November 22, 2018

We published a previous post on how our company trip to Write the Docs Prague went in September.

We mentioned that we had brainstormed our new documentation strategy on Writing Day, and we wanted to share the full extent of what we learned during that session.

Discussing documentation

First of all, it was fantastic to have a platform that was entirely focused on documentation.

It meant that we ended up having some very enlightening discussions about our documentation strategy – or what was then a lack of strategy. It helped us start to move forward in terms of how and what we would like to document for KnowledgeOwl.

We learned that there are two core categories of documentation for our company. These are:

a) Product/software documentation

b) Internal documentation

The product documentation benefits both our support team and customers directly by providing a shared information repository for our software. The internal documentation is more beneficial for our steadily growing team and will improve productivity in the long-term.

These two types of documentation require very different approaches to produce, although we see them both as serving our community of customers and team members.

Internal documentation

As we’ve grown, we’ve chosen to allocate our resources towards taking care of our customers. As a result, we haven’t kept our internal documentation as up-to-date as we would like. And operating as a small team means most information can easily be passed on through a Slack conversation.

Ultimately though, investing in your internal documentation can unlock your growth as a company. While we already have a ton of documentation behind the scenes, most of it’s not in a format that’s particularly user-friendly. It also needs to be revised and restructured.

We’re particularly interested in improving our onboarding process for new team members. This move has huge potential to save us time, as better internal documentation will mean that it’s quicker and easier for new team members to get up and running.

It will standardize some of our key procedures as our small team continues to grow. This will be an ongoing effort as we start to try to formalize some of our company structure.

We also need to produce some exciting policy documentation in order to comply with key requirements set by our expanding base of enterprise customers.

Our aim is to write this documentation in such a way that is not only compliant – but also written in plain language that can be easily understood.

Product documentation

Product documentation is – in some ways – almost an entirely different concern to internal documentation. That’s why a very large chunk of our time on Writing Day was spent restructuring our customer knowledge base.

Category restructure

The biggest achievement on the day was rearranging all of our existing content into new categories based on tasks. These are:

1. Account administration

2. Content management

3. Knowledge base administration

4. Developer documentation

New knowledge base categories

These new categories are much more reflective of the current roles that people have when interacting with our software.

We also went through and recorded what documentation we already had, and tried to think of what content we urgently need to produce.

Just In Time documentation

Instead of a massive documentation project, we will document exactly what we need, when we need it. That’s why we are thinking about using a Just In Time documentation strategy.

The support team will flag tickets that they think should be turned into documentation for customers. Then, either that team member, or someone else responsible for technical writing, will turn these issues into documentation to be published on our knowledge base.

This will be a team effort since we see documentation as everyone’s responsibility. A lot of the product documentation really needs to come from the support team, who are the ones talking to our customers day-in, day-out.

That means building documentation into our support roles so we can comfortably devote time to this important effort – even when things get busy. And we’re always busy.

Looking after our customers

We know that our approach to documentation is incredibly important.

That’s because product documentation is about the customer. Customers expect and need thorough documentation to understand some of our product features. They need tutorials to instruct them on how to make the most of our software.

In particular, our software has some very specialist functionality that needed more documentation than we currently had.

One of our customers working with us at Write the Docs is kindly producing this documentation for us. They reviewed one of the sections that they used the most and created a suggested structure for us. This customer is involved in some complex custom integrations, so having documentation from them has been very useful.

Customers gain much more value from KnowledgeOwl if we document our software properly.

Brainstorming on Writing Day

We used several techniques to brainstorm our documentation strategy at Write the Docs.

This included making a Trello Board, thinking about new Information Architecture, using mindmapping software, and allowing everyone to use their own creative process.

We also used our own version of card sorting – which involved posting post-it notes on a whiteboard. Other people were interested in this activity, and many were going through the same process with their own documentation.

Final remarks

We want to invest in documentation and make it part of everybody’s role at KnowledgeOwl.

It’s a work in progress. We know documentation is so important, but it’s challenging when it’s not anyone’s core responsibility. Maybe that is something that needs to change.

We gained a lot of value from the whole team coming together to learn more about our current and past approaches to documentation. We hope you learned something useful from this blog post that you can use in your own documentation efforts.

KnowledgeOwl is our knowledge base software that helps you produce amazing documentation. Take it for a free spin!