10 Tips to Improve Your Documentation
Beyond the standard “Know your audience”.
Alright, spoilers: You still need to know your audience. For tips on performing audience analysis, check out my article below:
Without further ado, let’s dive right in.
1. Spend more time on research
You can’t explain something you don’t understand. As much as everyone might wish this to be true, you can’t just sit in front of a blank document and write.
Most of your time will be spent researching and understanding what you’re supposed to be writing about. To frame it another way, research is the foundation of writing.
The better you research and understand the concept you’re writing about, the easier it will be to explain it in simple terms. Just like writing, research is iterative!
You may get to the writing stage and realize you don’t have a solid understanding of something, or that you’ve completely missed a concept in your initial research. That’s fine — as long as you go and dedicate more time to filling in the gaps.
Looking back at my time tracking from the past year, I average anywhere from 30 minutes to 2 hours on research for a given assignment, depending on various factors like:
- My familiarity with the subject
- The complexity of the subject
- The thoroughness of documentation required
Obviously researching troubleshooting steps for a short article will take less time than that of a quick start guide, but less research doesn’t mean no research.
As you get more comfortable with your research skills, you’ll learn to judge how much time you might need to spend on research — so make sure to include that in your scope! I’ve developed a funnel of sorts for how I search for information. It looks something like this:
- Search our published documentation
- Search our archives
- Search Confluence and Jira
- Google keywords (if they’re not product-specific)
- Ping my PM, QA lead, or SME (short questions)
- Schedule a meeting with SMEs (in-depth questions)
I’ll spend maybe a few minutes on each step before moving on if I can’t find anything. If I run down my list and land at scheduling a meeting, I know I’m not going to be wasting anyone’s time: I literally cannot find the information elsewhere.
💡 Tip: When you start new documentation, block time off on your calendar just for research.
Be kind to yourself, and learn how to research effectively.
2. Perfect the art of quick and dirty outlines
You’ve probably been writing outlines since your first year of high school English — nobody needs to be sold on the merits of an outline anymore. But to really get the most bang for your buck, learn the quick and dirty method.
Outlining and researching go hand-in-hand, so ideally you should be working on your outline during your initial research and planning.
Here’s how I approach outlines:
- Pick a template. For sanity’s sake, I highly recommend creating a set of templates for common articles (troubleshooting, how-to, user guide). This will help immensely with creating a structure to your documentation, saves time, and makes your documentation more consistent as a whole.
- List the tasks or concepts you need to cover. In a perfect world, you’ll get this from a planning meeting with your PM or SME. If you have enough product knowledge, this can be simple enough to determine, but it’s worth confirming. Nothing is worse than getting an initial draft out there and being told you’ve skipped something (or worse, wrote about something you didn’t need to).
- Organize the tasks or concepts in a logical order. This can take some time to get the hang of, and nobody truly masters information architecture. Tasks are generally chronological, while concepts can be more abstract. When I’m explaining concepts, I tend to partition: explain the context, then each individual part as it pertains to the whole, getting increasingly granular.
- Copy your research into the relevant section. If I’ve been researching simultaneously, then I know exactly where to go to fill in the blanks. Otherwise — meeting time!
- Get an outside opinion. I don’t always do this, but I consider it a good fallback when I’m wobbling between different ways to structure a document. Having a novice user run through your outline (and even initial draft) can dramatically impact the way you approach a document.
Once you have your outline, make a copy and start writing! I don’t recommend writing directly on your outline, because it helps to have something to point back to if you need to make any major changes.
3. Beware scope creep
A bane in the software world, scope creep doesn’t just affect engineering teams.
Technical writers often have to approach writing in a waterfall approach: the bulk of our writing usually happens after development has finished. That means the more bells and whistles the dev team adds, the more you’ll need to document. With a good PM (or a dev who knows their limits), this might not be a problem.
However, besides inherited scope creep, this issue manifests differently for technical writers than it does for engineers.
- Engineers: Found a bug or decided that additional requirements or features should be added to the project.
- Technical Writers: Set out to document one article, which suddenly turned into three or four articles that cover every possible facet in painstaking detail. And… ooh that tangentially related article is outdated, let’s add it to the list.
Scope creep is complex and can be caused by a wide number of factors. To combat scope creep in your writing, ensure you’ve clearly established the goal and scope of the documentation in your initial planning. Determine how you’ll handle supplemental information or additional instructions as they arise. You may know at the outset if your deadline is flexible, or if you have the resources to take on more content.
Learn to recognize what details must be included, and what are just “nice to have”. Track those “nice to have”s to be picked up at a later date.
4. Make your documentation scannable
Here’s a fun fact! According to studies by the Nielson Norman Group, 79% of users skim for information rather than reading word-by-word.
You’re probably skimming through this right now.
Skimming is the new normal, born from the veritable sea of information that is the internet. Our time is valuable, and when we start reading, we want to know immediately whether this tiny raindrop of content has the information we’re looking for.
How do you cater to people who skim?
- Provide meaningful headings and sub-headings. Don’t be clever, be clear.
- Start with the conclusion. From a famous speech expert, “Tell the audience what you’re going to say, say it; then tell them what you’ve said” (Dale Carnegie).
- Introduce new concepts in new paragraphs. We tend to read the first few words before moving on, so your readers may miss your point if you bury the lede.
- Half the word count. Then half it again. The trick of this is to be concise without losing any meaning.
- Use bulleted lists and images. They break up the wall of text.
Additionally, aim to make reading your content painless by simplifying your language.
5. Simplify your language
The use of plain language is so important in documentation that federal agencies are required by law to use words the general public can understand.
While you may not be bound by law to write simply, using plain language is still vital. It helps your readers easily find what they need, understand what they find, and use that information effectively.
To illustrate just how much plain language affects readability, which of these is easier for you to read?
A: It is important to note that the user should be very careful when adding, editing, or deleting portions of his or her source code.
B: Be careful when modifying your source code.
Simplified language affects the readability of your documentation just as much as your formatting. It won’t matter that your page is perfectly designed for scannability if reading your content gives everyone a headache.
There are a lot of great resources on writing plainly, such as:
- Free Technical Writing course (Google)
- Five Steps to Plain Language (Center for Plain Language)
- Federal Plain Language Guidelines (plainlanguage.gov)
- Plain Language is for Everyone, Even Experts (Nielsen Norman Group)
6. Use examples and analogies
Have you ever tried to explain something to a friend or coworker, and found yourself repeating your explanation over and over in slightly more creative ways because they just don’t get it?
I’ve found this happens most often when trying to explain abstract concepts.
The ability to understand and communicate abstract concepts (ideas that have no physical form, such as cloud computing or AI) is paramount in technical writing, second only to writing clear and concise instructions.
A perfectly decent explanation can be crippled without proper reinforcement. So how do you reinforce an explanation? Examples and analogies.
Real-world example
To better get an idea of what this looks like, let’s break down an excerpt from an article I wrote explaining what a webhook is.
Explanation: We begin by describing a webhook, elaborating on terms or concepts that might be confusing to a layman (like “event reactions” or “payloads”)
Webhooks are one of the ways applications can communicate with each other. They are a useful, resource-light way to implement event reactions, which means a specific action will be triggered when an event occurs.
Webhooks usually contain JSON payloads — your data — which is sent to a unique URL.
Analogy: Then we equate aspects that may be confusing to more concrete concepts. Here this means likening pinging a URL to calling a phone number.
The URL acts like a phone number for the originating application to call the target application. When that call comes through, the two apps communicate what data should be sent, and the target application gets to work.
Example: Finally we reinforce our explanation with a real-world example. The goal is to include each potentially foreign aspect of our explanation in our example.
For example, say you run an online business and want to create an invoice each time a customer completes an order. You would need to first set up everything in your invoice app, and copy its webhook URL.
Then you can tell the originating app — your online store — the webhook URL of your invoice app.
Now whenever your online store receives an order, it will encode all the necessary data (your payload) and ping the webhook URL, sending the order details to your invoice app to create a new invoice.
If you were presented with just the explanation, you would likely get a vague understanding of what a webhook is, but you may be hard-pressed to explain it to someone else.
By reinforcing the concept with an analogy and example, the explanation is more likely to stick.
7. Address the user directly
This one is a topic of contention in some circles, but I side on the team of giants like Microsoft and Google: use second person (you).
Some argue that technical documentation should be written like scientific papers, others feel that technical accuracy and readability is more important (This divide is largely between the medical and software fields, respectively).
Take a look at these different ways to give instructions:
- First-person plural: We should turn the lever clockwise 90°.
- Second-person singular: You should turn the lever clockwise 90°.
- Third-person singular: The user should turn the lever clockwise 90°.
- Imperative: Turn the lever clockwise 90°.
- Passive: The lever should be turned clockwise 90°.
Which reads most naturally to you?
It’s most likely the imperative or second-person singular. As a general rule, I recommend using imperative statements as your default for instructions, and second-person if you need an explicit subject.
Avoid using passive voice unless it’s unclear or unimportant who is performing the action, or when you want to avoid assigning blame to the user (such as in error messages).
8. Avoid time-sensitive statements
Few things are as frustrating as trying to manage updates to documents that are constantly facing obsolescence.
The simplest way to keep documentation maintenance low is to avoid time-sensitive statements. Examples include:
- Listing all applicable versions: Instead of “This applies to version 1.2, 1.3 and 1.4” try “This applies to version 1.2 and above”.
- Using too many UI screenshots: While screenshots can provide much-needed context, minimize your use of UI screenshots to lower the volume of updates that may be needed as the software changes.
- Using ‘currently’: It may seem like you’re softening a rough blow by saying “We currently don’t support…”, but users usually read that as “We’re planning to support…in the future”. Unless you know this is true, avoid using ‘currently’ in your documentation.
Keep your writing timeless whenever possible.
9. Learn to edit effectively
Your first draft should never be your last draft. Filling a blank page with words is hard enough, nevermind getting everything grammatically correct, well-organized, coherent, and devoid of fluff (like this sentence).
Google’s Technical Writing Two course covers great first steps for self-editing:
- Edit to follow your style guide.
- Step back and read your draft from your audience’s point of view.
- Read it out loud, or use a screen reader to find awkward phrasing.
- Come back to it later.
- Change the context, like printing a hard copy or changing the font.
- Find a peer editor.
I recommend developing some sort of editing checklist, such as this Guide to Self-Editing from the University of New Hampshire. Not only will it save you brainpower, but it will help your documentation become more consistent in the long run.
10. Test your instructions
Testing your documentation is important. It helps ensure your instructions are accurate, timely, and make sense to the user.
A core tenet of user-centered documentation, testing isn’t just smart, it’s almost fun.
I think Tom Johnson put it best:
Only when you get your synapses firing in the knowledge domain you’re writing in, as well as your hands dirty testing and trying out all the steps and processes, does the work of technical writing start to become engaging.
The actual steps for testing your documentation will largely depend on what kind of system you’re documenting, and what your skill level is. At a minimum, you should have access to a test environment where you can follow along with your steps as you write.
You may have to go through hurdles to get access, but having access to a test environment makes a marked difference in the quality of your documentation. There’s no comparison between writing up instructions based on something that is explained to you, versus writing up instructions based on something that you have done yourself.
Good developers (and good Product Managers) understand this need, and will usually accommodate getting you set up.
Besides testing your instructions, make sure to test your documentation as a whole. This can mean:
- Checking any links so your users don’t hit dead ends
- Testing any commands, or confirming their accuracy with an SME
- Compare to your baseline or outline to ensure you haven’t left out any important sections or concepts.
Conclusion
Thanks for reading! If you found these tips helpful, or have any tips of your own, feel free to leave a comment! 👋
