Three Quick Docs Wins
— Continual Improvement, Technical Writing — 5 min read
Simplicity in technical documentation can be elusive. The content is, by nature, complex, so just having all the content collected and accurate can feel like a monumental task. And it is! If your docs are accurate and complete, you’ve won a major battle. Once you’re past the initial draft stage, though, you’re ready to start revising to make your content as user-friendly as possible.
Below are three tips you can use to improve the quality of your technical documentation in under an hour.
While there are many routes you can take to improve the quality of your documentation over time, I recommend starting with the following three:
Remove Marketing Language
There are some words that (almost) never belong in technical writing. These include:
- Simply
- Simple
- Easily
- Easy
- Just (For example: “Just do X” or “Just do Y”)
Words that extol the usability of a certain feature belong in marketing content. Once a user is in the realm of using a product, these words should generally be avoided. Imagine: you’ve just finished reading about how easy a feature is to use, you give it a try locally and… you get stuck. Now, you feel foolish because the feature was so easy! Anyone should be able to do it. This is far from ideal if the goal is making documentation inviting to new or beginning users.
If you happen to be a developer or product manager who’s been involved in the creation of a feature, it’s also understandable why you may feel inclined to slip words like the above in: you’ve poured hours upon hours of effort into making the product as simple as possible. It should be easy for the user to implement too! But, in fact, talking about how easy a feature is to implement can often make it more frustrating for the end-user.
Another note, telling a user that a feature is so easy can even make your documentation look bad: If the feature is so easy the tutorial must either be really bad or the user must be missing something very obvious. Neither option is something you want your users to be wondering about—especially if they’re just getting started and still have the option to switch to a competitor.
My recommendation: use an automated tool to catch any instances of these words that may have slipped in prior to publication.
I’ve used Textlint’s stop words rule in the past, it works great for content in any markup language.
Use Consistent Terminology
Inconsistent terminology is a really easy trap to fall into—particularly in the earliest stages of documentation. When a feature goes through the stages of the development process, from planning to release, it’s common for multiple variations of a name to exist. Maybe the dev team has one or two different names during the development lifecycle, while the marketing team picks another term for branding or SEO purposes.
This isn’t a problem for those familiar with a product, but even a slight variation can cause confusion for new users. If I’m completely unfamiliar with your product, I’m not sure if 'Product X' and 'Prod Ex' are the same thing. Maybe I’m 90% sure they are… But that extra cognitive load is definitely not something you want the end user to be carrying while they read your technical content.
My recommendation: Once a product has its official name, create a list of all the variants that have been used in the past. Store this list in your style guide. Enforce it automatically, if possible. (If you’re using Textlint’s stop words you can also add these variants to your list of words to avoid.)
Note: If you need to use multiple terms for the same product for SEO purposes, keep in mind where you want users to land when searching for those terms: usually a marketing page.
Use Active Voice
Use active voice as much as possible. Active voice also happens to be one of the easiest ways to improve readability score. Take the following example: “Feature X can be used…” vs “Use Feature X…”
It’s common to feel tempted to use passive language when writing a guide, especially during the information gathering stage. Once the content has been compiled, though, it’s important to guide a user through a process. That requires using active voice.
It can be uncomfortable to issue direct commands, and you might feel tempted to use less direct language. For example, if a user needs to add a list to their style guide it may feel more polite to write: “This list may be kept in your style guide” or “Your style guide may be a good place to keep this list”
However, by instead saying: “Keep this list in your style guide” you’ve given the reader clear, direct instructions and reduced their cognitive load. If you need to clarify that the step isn’t required, you can include the word optional. (For example: “Optional: Keep this list in your style guide.”)
My Recommendation: Automate checking your content for active voice prior to publication. This can be done using Vale, or Grammarly. (There's a fair amount of overlap between Vale and Textlint. Some features do not exist in both tools.)
Summary
Just like software, technical documentation can and should be continually improved. Once you have minimum viable documentation, you can move on to creating a style guide, implementing great processes to improve internal publication experience and increase turn-around-time, and move on to incremental improvements.
As you improve over time, your end result will be amazing documentation that you and (more importantly) your end users love.