The Problem with our Documentation

We have a problem with the majority of our documentation as Software Engineers: when we do decide to write documentation, it tends to end up overly complicated, full of jargon, and unfocused. We spend hours on end trying to make sure we write the cleanest code possible, yet put very little thought into how we write our documentation.

One way to put more thought into our documentation is to simply spend more time on it. The issue is, at most companies we aren't given the time to do this - good documentation doesn't necessarily produce the short-term results that a business looks for.

Rather than spending time scrutinizing every paragraph and explanation you write, consider the following approach. Before writing anything down, spend 10 minutes doing some planning and determine a baseline and a scope for your documentation. This planning can not only make the writing process easier for you but also help the reader make the most out of your documentation. Let me elaborate.

Set a Baseline

Perhaps one of the hardest parts of technical writing is identifying the skillsets of your audience. You can publish a page to your team or organization, and have no idea who is going to end up reading it. Imagine writing some documentation on a very niche topic that builds upon many other concepts within your team's ecosystem. A seasoned veteran reading this will likely have no issues understanding your writing. However, what if a newbie to the team stumbles upon this documentation and tries to read through it? Suddenly, the documentation has done the opposite of what it has intended to do - the various jargon and implied knowledge throughout your document ended up making the topic more confusing for the reader, rather than less confusing.

A baseline of knowledge is the minimum amount of information required to understand the information you write in any given document. Before even beginning to write documentation, write out a bulleted list of all topics that you will assume are known by your audience. Place this bulleted list at the top of your page in its own section - perhaps label this section as "Baseline".

Here is an example baseline I would set for a page on learning Redux:

# Starting out with Redux

## Baseline

- Knowledge of React, particularly in: components, state, lifecycle, hooks
- Functional programming concepts: pure functions, side effects
- Immutability

Defining a baseline at the top of your page does a few things.

It makes it easier to write. By defining a baseline, you define a minimum set of knowledge that is now implied. You no longer have to describe any details of any of the topics you listed within the baseline. Technical jargon now becomes more helpful rather than confusing - I can now use the term "pure function" when describing a reducer in my Redux page, and be confident that the reader will know what that means. This allows me to be more concise.

It makes it easier for the audience to understand your writing. Now that there is a clear expectation set at the top of the page, a reader can evaluate how much they already know. They can choose to read up on these topics before continuing on with this particular document, rather than blindly diving into a piece of documentation. Once they are ready, they can come back to this documentation equipped with the knowledge they need to read through your explanations.

It identifies gaps in your ecosystem's documentation. Now that you have written a baseline, you can go through each item and link them to other resources and documentation to help the reader learn. This has the obvious benefit of making more documentation accessible to the reader, but it also helps to identify certain subject matters that are lacking in documentation. Note these subject matters down as future candidates for more documentation.

Set a Scope

Certain pieces of documentation try to cover too much at once. It is easy to separate topics at a macro level. Consider writing a set of documentation that will cover the entire animal kingdom. An obvious place to separate pages of documentation is between the different animals. We will write a separate page for a Bengal Tiger and another for the Northwest African Cheetah. This distinction is clear, but will we really be able to contain all information about the Bengal Tiger on one page? Likely not. We could write a page on the hunting habits of the Bengal Tiger, and another on their habitats. Even these topics might be too broad. Separating topics on a micro-scale is nuanced and often subjective, but ultimately important to keep your writing clear and concise.

A scope is the subject matter that your documentation will cover. Like with setting a baseline, you should set a scope for your page before you even begin writing it. Define a few bullet points that describe at a high level what your page will be about. Place them under the baseline section on your page, with a header named "Scope".

Here is an example scope I might set for the Redux page I mentioned above.

# Starting out with Redux

## Baseline

...

## Scope

- What problem does Redux solve?
- Application Structure
- The Store
- State, Actions, Reducers

Like defining a baseline, this accomplishes a few things for you.

It helps you divide on a micro scale. The act of outlining your desired scope for a page forces you to consider what content you include on the page. If you notice you have many topics listed under your scope, consider trying to break them up into a few categories and divide that content across multiple pages. Too many items within a scope can lead to long-drawn-out documents. Oftentimes, readers will have an easier time digesting information if it is broken up into clear discrete parts.

It keeps your writing on track. Now that you have a set of bullet points that outline what the page will cover, you have a defined starting point to start writing from. Pick a bullet point and start writing. Again, if you notice a particular topic starts to drag on, consider splitting it out into its own page with a baseline and scope of its own. The scope also defines a clear end state for the page - once documentation has been written for each item in the list of scope, then you know you are done. A well-defined scope keeps your documentation concise.

It signals to the reader what the page will cover. If the reader reads the scope and determines that this page does not cover what they need to learn, they can leave immediately and not waste any of their time reading the page. If the scope does cover what they would like to learn, now they know exactly what to expect from this page. Setting expectations upfront with the reader gives them a clear idea of what they are getting themselves into when sitting down to read your documentation.

The Takeaway

Defining a baseline and a scope are two easy and time-efficient ways to instantly improve your documentation. It aids tremendously in the writing process while giving the reader valuable information at the same time. Perhaps you already internally think through these two aspects before writing a page. Putting your thoughts down on paper like this brings that planning to another level - you are already thinking it, so why not put write it down?

This physical contract keeps the writer true to their original plan. It acts as a set of guiding principles that keep you the writer on topic. When a baseline is defined, there is no need to explain details of Topic A to the reader - they already know about it. When a scope is defined, there is no need to write any more or less than what is dictated by the scope. These two simple lists go a long way towards making your documentation more clear and concise.

If you've enjoyed this content, consider subscribing to my mailing list to be notified whenever I release new content.