Tools and techniques to overcome documentation writer’s block
Chances are we had a similar first experience with docs: you’ve been staring at a blinking cursor for more than you would like to admit. You seem to be in a good position: you have the knowledge the world needs. But there is no comfort in that if you just can’t seem to be able to put it on paper.
I urge you to consider this a chance to improve yourself as a communicator. No matter the form of communication, one ingredient of success stays the same: being mindful of the recipients’ attention and focusing on solving their problems.
In the next paragraphs, I would like to outline some common challenges that occur while documenting and share my experience dealing with them.
Problem 1: not knowing where to start
Sometimes, we just need to get the ball rolling. Unfortunately, when documenting we often get an inverse of what we know from software development (and other areas): the first 20% of work takes 80% of the time.
What I like to do right from the start is the following: list key points of what I want to get across with complete disregard for style and language.
Let’s illustrate it with an example of documenting an app understood as a listing in some sort of marketplace:
- the app is a feature extension mechanism for the core platform
- you can: register the app, retrieve information about it, delete it, deactivate it
- apps require specific permissions
Once I have these points, I start looking for patterns that may reveal the structure of the document I am writing. I want to establish that structure early so my next effort can be more focused.
In our example, I can see clearly that we have different actions that we can execute on an app. Since each of them deserves its own description, I can move it to separate sections, each starting with a heading:
## Registering the app
## Fetching the app information
## Deleting the app
## Deactivating the app
This may not look like much, but at least I know what I will be and will not be writing about inbetween those headings. By putting those pieces of information in the document, I relieved myself from having to think of them. Now, I can use the regained brain power to focus on what is still missing.
From looking at the outline of the article, as well as the original list we prepared, it becomes jarring that before we dive into “what can you do with a thing”, we probably have to tell “what is the thing” prior to that. So I add a new section before our actions:
## Overview
The app is a feature extension mechanism for the core platform...
## Registering the app
...
As you can see, the approach I suggest focuses on building the structure of the document early. By breaking it down, we go from a broad “describe how apps work” to focused “first describe what is an app, then describe how to register it, and then…” which should be easier to tackle. Once the structure is there, we can move on to the actual writing, which comes with its own set of problems.
Problem 2: chasing the perfect sentence
One of the sources of struggle I’ve seen often both in myself and other writers is expecting to get it right with the first go. This is hilariously clueless coming from developers: people who are used to getting things wrong all the time, and improving it gradually.
The experience of writing good documentation doesn’t have to differ that much from writing good code. Sometimes, you just need to finish the piece you are working on, fully aware it’s not perfect, and go on to the next thing.
If you find yourself getting stuck in an endless cycle of rewriting and refining, try the iterative approach. Instead of aiming for perfection right from the start, focus on getting your ideas down on paper without worrying too much about the quality of each sentence. Treat your first draft as a rough sketch, a foundation to build upon.
Once you have your initial draft, take a step back and give yourself some space. Allow your thoughts to settle and return to the draft with fresh eyes. Gradually start refining your sentences, but this time with the confidence of something (instead of nothing) being already there.
Remember, the perfect sentence may not be there on any given day, and that's okay. Your reader is not aware of the alternative universe where it exists, unlike you.
Problem 3: too much fluff
When our users are looking for answers in our documentation, we should assume their attention can be at its lowest. They just want to ship the bloody thing, not witness a rhetoric show performed by the documentation author.
We can use the words of Voltaire as inspiration: "The secret of being a bore is to tell everything”. If we are not mindful about what we include, the primary goal of our writing gets blurry even for us, the authors.
The fluff is not there out of spite. We can simply be unaware of the complexity language can add.
Consider the difference between these two sentences that are meant to express the same idea. The first one, however, is intentionally simple, while the latter requires your brain to work much harder:
The app allows users to extend the core platform with additional features.
vs.
The application empowers end-users to amplify the core platform's capabilities by seamlessly integrating supplementary features and functionalities.
If every sentence looks like this, the users can feel their attention being disrespected, turning somewhere else in result.
Luckily, there are tools that can pinpoint places where the complexity of our language is getting out of hand:
Hemingway App
Hemingway App is a simple text editor that focuses on giving you feedback about the language you are using. The objective is to make it clear and relatable. It enforces that by highlighting fragments that are too complex, use passive voice or words that can be replaced or omitted.
First time you paste your writing into the Hemingway App feels like a roast. The lessons learned will hopefully stay with you forever.
Simple English
An alternative to the above is Simple English checker. As a foundation, it uses the concept of Ogden’s Basic English which makes a point that we can express most ideas with much less words.
The tool allows you to either paste a plaintext content or point to a URL it’s supposed to analyze. In result, it marks words that are not present in the dictionary you picked (which deems them “complicated”). Once you realize how many of these words are present in your text, you can reconsider if they are truly needed.
Does these three problems exhaust the topic of overcoming writer’s block? Certainly not. I hope they at least urge you to explore the topic further.
Remember, the most important thing is to start. Once you have something, you can improve it. But you can’t improve nothing.