Simplifying Complex Technical Documentation

By November 5, 2013 February 27th, 2016 General

A company recently hired us to update their documentation for a new version of their software. However, some investigation revealed that doing the update was the least of their problems. Their documentation consisted of a number of PDF documents, each hundreds of pages long and very difficult to understand. So over the course of the last couple of months we worked hard to break this documentation down and simplify it. In this article we present some of our learning’s.

Probably the biggest problem we see in a lot of technical writing is assumptions about the reader’s knowledge level. This of course is easy to introduce when you’re developing a product on top of some sort of technology (e.g. we’ll use database systems for this article) which requires the user to already have a firm understanding of that underlying material. The problem however, is that not all users have the same level of understanding and this can happen for many reasons. For example, they may have been tasked with both learning about databases and your system at the same time. So in this case they may be relying on your documentation to fill in the gaps about how database systems work.

The solution here is to take a step back and provide some “handholding”. Don’t assume the reader is an expert in databases. Provide some conceptual material which non experts can use as a starting point into your documentation. This will also provide a refresher for advanced users allowing them to quickly understand the context in which your product fits into their understanding of the bigger picture.

If there are other external documents (e.g. from other companies) out there, be sure to create a formal section introducing those resources, what they provide, how they relate to your product, and why the reader should consult them. Avoid the temptation to just list a bunch of resources without providing any context around why they should be consulted. The goal is to help the reader every step of the way and this includes spending the time in helping them understand documents written by others.

Just as importantly, always include a formal introduction as to what problem the reader is trying to solve by using your product before getting into the details of your product. It may sound obvious, but the majority of highly technical documentation we come across fails to do this. This often occurs because subject matter experts have been the prime contributors, and often make assumptions or don’t understand the reader’s level of knowledge. Hence, this is where a technical writer is invaluable as they can bridge that gap between your readers and the content writers.

Breaking information down into sub documents is also essential in making it more consumable. In the case of our client, their PDF files were hundreds of pages long and included everything from installation, to conceptual material, to develop guides. On top of this they also assumed the reader understood what problem their software was solving. The solution we came up with was to break this information into three separate guides: an overview guide explaining the underlying technology and what problems the software was solving, an installation guide containing all of the steps to setup a dev environment and get to a break point, and finally a developer guide (actually two) for the different languages that developers could extend the product with. This breakdown made it easy to know where to start and was less daunting for reader’s to consume.

Finally we should mention that constructing these materials is actually best done in the opposite order of how the reader would consume them (i.e. write the developer guides and quick start guides first, followed by the overview guide). This is essential in order to understand the details before being able to summarize and provide overview material. In other words, only once you understand the subject matter can you summarize it for your readers.

So if your documents are becoming excessively long and users are finding them difficult to consume, take some time to understand the reader’s knowledge level and whether your documents explain the whats and whys before the hows. Spending this effort will go a long way in allowing your reader’s to get the most from your documents.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.