How to Write Technical Documentation That People Will Actually Read and Use
Understanding for whom you are writing, how to put your ideas together, and why you’re writing are critical to ensuring your technical documentation is useful and worthwhile
It‘s the end of a major project milestone and you have completed your work — you’ve done it! You’ve met all your goals and shipped an amazing product to production. There’s just one problem: no one knows how to use it except for you, and you’re about to leave for a six-month around-the-world vacation!
(You’re very successful!)
No problem — you’ve got this! You start to write everything down … except you don’t remember how it was that you solved that one issue four months ago or overcame a major hurdle last year. Much of what you’re writing assumes the reader knows as much as you do. And, to be honest, you don’t even remember how some of the parts are connected or exactly how they should work together.
Now what??!!
The scenario above is all too common. Documentation — especially technical documentation — is often written after everything is done and with the time remaining before a deadline. We forget crucial steps in our instructions and make assumptions as to our readers’ experience and knowledge. This all makes for documentation that is difficult to read and, even worse, discouraging to its readers.
In this article, we’ll walk through how to approach technical documentation, when to do it, what to consider while you’re writing it, and why it’s so important. But first, let’s answer the question …
What Is “Technical Documentation”?
Before we talk about documentation approaches, when to do it, etc., we need to understand what we’re talking about. We’ll be discussing documentation as a written description of whatever you’ve worked on, with instructions on how to use it. This definition applies to technical documentation, too.
For the purposes of this article, “technical documentation” will be demonstrated through documenting software; however, many of the ideas are universal. They could just as easily apply to systems, a user guide, or anything technical. Also, we will be discussing …
Why Is Good Documentation So Important?
Good documentation will act as your reader’s guide through your product. It helps your reader understand what you’ve done, why it’s important, and how it works. You want it to guide your readers, answer their questions, and educate them on as many important aspects of your product as possible.
Without good documentation, your readers will likely not be able to use your product to its fullest potential, if at all. Functionality and details will be missed, especially for anything that is subtle. As the complexity of your product increases, the quality of your documentation becomes more critical.
When Is the Right Time to Write Documentation?
Often we think of documentation as the final thing to do. We have a task or goal in mind, we work hard to achieve it the best we can, and we start writing the documentation once finished.
I would argue that this is the worst time to document anything, aside from never at all.
Really?! The end is the worst time? But isn’t that when you would have clarity on the achievement as a whole, complete object?
Yes! Here’s why. Waiting until the end — though better than no documentation at all — will lead to weaker documentation that is further removed from the implementation. By the time you have finished your work, it’s likely that you’ve already started forgetting some of the more granular details that got you there. This effect is even more acute for anything of significance or complexity.
Documentation doesn’t live in a bubble. It’s not a stand-alone product. You can’t have documentation without the thing you’re documenting. It has a symbiotic relationship in the development process that is often overlooked, undervalued, and neglected.
Instead, document as you go along, step by step. This approach is especially useful when learning a new skill or process. Keep your documentation open and close so that you can easily write your latest insights. Finally, at the end, use the remaining time to edit the documentation and take it from good to great.
What’s the Difference between “Good” Documentation and “Bad” Documentation?
We have all read through instructions that, by the end, prove to be more frustrating than if there were none at all. Steps seem to be missing. You can’t understand the intent of the text. The author made assumptions that make you feel inferior. You try to work through it all but eventually you throw your hands in the air in disgust and do a Google search for a different answer. You are the victim of bad documentation!
Good documentation guides you without being condescending or assuming your experience. It reads clean, has clear and reproducible steps, and will result in completing the task you set out to do.
How Do You Write Good Documentation?
Follow these rules to write good documentation …
Write for Your Audience
It is essential that you know your audience so that you can write to their level. This can be tricky, as over- or underestimating your audience will likely make your documentation difficult to use for the actual audience you’re writing for. Assumptions of their knowledge can be exclusionary if you’re not careful.
For example, let’s say you’re documenting a test automation suite for a website. If you assume your audience knows the system and how to run the suite, you might begin your instructions with “Step 1. Get the website running locally.” This assumption — that the reader will know how to “get the website running locally” — excludes anyone who doesn’t intrinsically know how to do that. Anything that follows may be useless to them. This may also demoralize the user — if they don’t know this basic first step, how could they hope to be successful?
The other end of assuming is believing the audience knows nothing. Imagine experienced quality engineers (QEs) are your audience. If your documentation reads like it’s talking to non-technical people, the experienced QE may get bored and feel that you’re talking down to them.
Finding the sweet spot is somewhere in between. From our example above, think about who might be executing the test automation suite — QEs and developers, most likely. If it’s any good, you should hope folks will be using it for years. This means, eventually, some people will be coming to it fresh and without any background while others may just need a refresher.
So how do you serve both audiences — those that are familiar with the product and those that are new to it?
Use Modular Documentation
Going back to the first instruction example above — “1. Get the website running locally” — could it be that maybe this isn’t such a bad first step? After all, for those that have been using your excellent software for years, they may not need more than that. But what do you do for those that do need that help?
Write more documentation!
(Come on, you had to know my solution was more documentation.)
More precisely, look to see if there is already documentation on “getting the website to run locally.” If there is, great! Just be sure that it still works and, if it does, link to it in that first step. If not, write a new documentation page to instruct people on how to get the website running locally.
Making your documentation modular allows both audiences the grace to proceed at their level. It lets the experts get through this step quickly and without too much fuss while enabling the newcomers to dig deeper and walk through something they haven’t seen before. Everyone wins!
Have It Reviewed
The last thing to do before you can consider your documentation complete is to have it reviewed. Ideally, a peer who can validate your documentation should perform the review. Also, strive to have it reviewed by a potential audience member if possible.
A perfect example of this is onboarding documentation. (Onboarding documentation is typically written to help people who are new to a project/organization and need guidance on how to get up to speed.) The people who usually write this kind of documentation don’t always recall what was necessary and important to a person who is new. Thus, it is easy to make assumptions and forget important details.
To ensure the onboarding documentation is thorough and accurate, it should be reviewed by someone who is actually going through the process. Sit with the onboarding person and observe them as they use the documentation. Note any difficulties, confusion, or questions they have and update the documentation. Add any missing steps or omitted details. Repeat with another onboarding person until your documentation is usable without needing further assistance.
Now that you know what good documentation is, why it’s important, when you should write it, and how to make it, it’s time to enjoy that around-the-world vacation. Set sail with the knowledge that those still at work will be able to use your product to its fullest potential, leaving you fulfilled and carefree! Bon voyage!
