Technical Writing Best Practices to Keep In Mind

Technical writing goes beyond presenting isolated pieces of information.

To help the users understand the product, you have to display the information in a way that lets them learn about the product and solve problems effortlessly.

Since that can be a demanding task, we’ve prepared a guide with best practices for technical writing you can implement to make your product documentation an informative and comprehensible resource.

So, let’s see how you can write technical documents users will find helpful and actually want to read!

Plan Ahead#

Starting writing and then going where it leads you is a valid approach in creative writing.

However, the purpose of technical writing is to present technical information, and to do that successfully, you’ll need a thorough planning session before putting your thoughts into words.

With so many steps that technical writing involves, you won’t find a universally accepted formula for organizing the writing process.

Still, almost all writing guides recommend starting with planning.

For instance, this University of Victoria open textbook on technical writing places collecting information and creating the outline at the beginning of the writing process.

Source: University of Victoria

In other words, you shouldn’t start writing without a plan, and a great place to start planning is to identify your audience.

Knowing if you’re talking to experienced Java developers or end-users trying to set up an app will help you determine the right writing style and the amount of jargon to use.

You can use the following set of questions provided by the Writing Commons encyclopedia to see if you should write for specific or generic audiences:

1. Who specifically is your reader? Are there multiple readers?
2. What do your readers already know about the subject?
3. Do you need to modify your message for international readers? Are there cultural issues that you need to address or avoid?

If you can’t answer these questions on your own, you should ask the project leader for input. Remember, technical documentation is only useful if it meets the audience’s needs.

Your finished audience analysis should look something like this:

Source: Google Developers

It’s also helpful to take note of the cultural background of your audience—you don’t want too many idioms confusing your international readers, for instance.

After you’ve identified the audience, you can continue with planning the outline.

While some tech writers stand by defining headings in advance, others advocate establishing the content of the sections first and labeling them later.

Here you can see a dialogue between two technical writers with differing viewpoints discussing the best practices for planning the content.

Source: Hashnode

There’s no right or wrong here—you have to find an approach that works for you.

Still, whether you plan the exact titles or go with short placeholder descriptions, a thought-out plan will direct your writing efforts and help you present information in a logical order.

Use Terms Consistently#

Whatever technical writing resources you reference, you’ll notice a common element popping up in all of them: a plea to writers to use the terminology consistently.

Source: Microsoft

Consistent terminology helps users understand the materials, so you should use the same version of a term each time you refer to it.

As a writer, it’s probably in your nature to use synonyms to captivate your readers.

Let’s examine a well-known example. Homer didn’t only use the name Poseidon to refer to the god; he also used epithets such as blue girdler of the islands or god of earthquakes.

While that undoubtedly makes for beautiful writing, try to imagine how confused your readers would feel if you suddenly started referring to menu commands as menu options or menu items.

The authors of Google’s technical writing course have an excellent take on the importance of using terms consistently:

“If you change the name of a variable midway through a method, your code won’t compile. Similarly, if you rename a term in the middle of a document, your ideas won’t compile (in your users’ heads).”

In addition to sticking to one word for one thing, you should also watch out for terms with similar but distinct meanings and avoid using them interchangeably.

Here are some common examples you should be aware of:

• environment, platform
• version, release
• panel, screen
• window, dialog box

Inconsistent writing is one of the most prevailing technical writing mistakes. Luckily, it’s also among the easiest ones to fix.

Even if you’ve already written a significant portion of technical documentation, you can still retroactively tackle the terminology inconsistencies by using the find and replace tool.

The tool is available in most writing and editing platforms. Here’s what it looks like in Google Docs.

Source: Google Docs

However, you’ll be able to save time by using consistent terminology from the get-go. Your technical editor will be thankful, too.

One of the best practices you can implement to ensure consistency is creating a dos and don'ts table with preferred technical terms.

We’ve gathered some examples from the SUSE Documentation Style Guide to paint the picture of what it could look like.

**Accepted

Rejected**

hard disk

HDD, HD, hard disc [misspelling], hard disk drive, hard drive, hard-disk, hard-drive, harddisk, harddrive, hdd, hd

kernel space

kernel-space, kernelspace, kernelland

text box

entry area, entry box, entry field, input area, input box, input field, text area, text field

All in all, if you want the readers to understand the instructions you’ve meticulously planned, you should make it easy for them, which you can do by using technical terms consistently.

Another method you can use to facilitate understanding is implementing visual elements. Keep reading to see how!

Use Plenty of Visuals#

Incorporating visual elements in documentation is one of the best practices you can do to take your technical writing to the next level.

They help readers understand and retain information while making the content look polished—what’s not to like?

You may now be thinking that you haven’t seen too many images in professional content, but we’ll ask you to reconsider the thought.

For instance, when you buy a piece of furniture, you usually get an assembly manual with it.

Verbal instructions there are optional. Most manuals rely heavily on illustrations because visual elements are an excellent way to present information more clearly.

However, it would be a mistake to think that you can only use visuals when presenting physical products.

If the product you’re writing about has any sort of user interface, your technical documentation has to include screenshots.

Let’s look at how ChartHop, a people analytics software, enriches the product documentation with screenshots.

Source: ChartHop

In the example above, the authors didn’t restrict the software description to words. Instead, they’ve captured screenshots of the solution and used those as the base for the instructions.

That way, when users start using the software, they won’t have to comb for features; they’ll already know what the solution looks like.

To get the most out of screenshots, you should supplement them with annotations.

For instance, the part of ChartHop’s documentation that talks about filters starts with the screenshot of a visibly marked filter tool.

Source: ChartHop

Boxes, arrows, and lines help direct the attention to the relevant part of the image you’re showing.

Screenshots aren’t the only visual elements you can use to simplify the information. Charts, gifs, and diagrams can also help you translate complex ideas into a more manageable format.

We’ll now look at an example from the product documentation of Vizury, an omnichannel marketing platform.

Source: Vizury

In the image above, you can see a diagram depicting Vizury’s feedback management system.

Diagrams like this one explain relationships between components more effectively than the walls of text you’d have to write to convey the same information.

If you plan to include lots of visuals in your documentation, choose a dependable publishing tool—no one wants to waste valuable time inserting and formatting visual elements.

The examples of technical documentation we’ve just seen, those of ChartHop and Vizury, were created with Archbee, our product documentation platform.

Source: Archbee

Our clients love the ease with which you can “incorporate images, code, diagrams, and almost anything you can imagine.”

So, if you’re looking for a platform that helps you create user-friendly technical documentation, Archbee may be the solution for you.

We integrate with popular diagramming tools, making the process of adding visuals even smoother.

Make Your Content Easy to Skim#

One of the best practices in technical writing is making the content skimmable.

Organizing documentation in a way that highlights the most important information makes the content approachable and lets your readers know you respect their time.

Back in 2006, the Nielsen Norman Group found that readers first read content in a horizontal movement across the upper part of the post.

After another, shorter, horizontal movement, they scan the content’s left side vertically. Based on the format, this is called the F-shaped reading pattern.

The group repeated the study eleven years later, using a more modern form of content, and found that nothing has changed about how we read to find information.

Source: Nielsen Norman Group

These findings tell us that readers mostly look at headlines and opening sentences without paying much attention to information sandwiched in the dense paragraphs.

So, if you don’t want the crucial parts of your documentation ignored, you should be mindful of how you arrange the information.

The inverted pyramid method is an excellent way to structure technical documentation.

Source: Wikipedia

The method boils down to putting critical information first. If there is any optional or background info, you should place it at the bottom of the document.

That way, even the F-pattern readers can skim the content without missing out on essential information.

Another benefit of this approach is that you’ll receive fewer support tickets for the things that you’ve described in the documentation, but the users haven’t read.

So, how does this look in practice? Let’s return to ChartHop’s documentation and see.

If you look at the red boxes we’ve used to mark the structure of the documentation about importing payroll data, you’ll recognize the familiar shape of the letter F.

Source: ChartHop

The documentation first tells you that you can import payroll data from an external app. Next, there are direct instructions on how to do that.

Notice that the content that isn’t relevant to every user—the section on using IDs instead of emails—is placed at the bottom so it doesn’t crowd the essential information.

The skimmability of the document is also improved with the use of bullet lists.

Additionally, ChartHop uses descriptive headlines so that users can skim the table of contents for the topic they need.

So, unless you’re writing a gazpacho recipe for an SEO-driven blog, it’s best to leave out the stories about your grandma’s childhood.

Technical documentation aims to provide helpful information about the product, so make sure you stick to essentials and draw your readers’ attention where needed with skimmable structuring.

Test Your Instructions#

If you want to ensure the accuracy of your technical writing and provide the readers with a smooth user experience, then the best practice you can implement is to test all the instructions you’ve laid out.

After all that content planning, writing, and shaping, it would be a shame if your technical documentation turned out unusable due to errors in the subject matter or wording.

Believe it or not, mistakes can even be a result of your technical proficiency.

When you’re the expert on the subject, you may unintentionally overlook some steps that are obvious to you, but not so much to regular users.

Asking other team members to carry out your instructions line by line can give you some insight into whether you’ve described all the steps clearly.

It may turn out that you’ve forgotten to include a crucial step just because it’s very simple, like in the following example.

Source: Twitter

To prevent such situations, you have to test several aspects of the documentation. We’ve compiled a checklist of documentation elements that you should test before publishing.

• Ease of understanding
• Grammar
• Accuracy
• Completeness
• Structure and navigation
• Sequence of actions
• Vocabulary

So, if the author of the tweet we’ve seen had tested the documentation for completeness and sequence of actions, the instructions would have been more successful.

If you’re writing technical documentation for software products, you also should double-check all the code because it’s often considered the most important part of the documentation.

Write the Docs has a great guide on tools for testing the code in documentation, so make sure you check it out.

After you’ve made sure the instructions are accurate and easy to follow, you should do one final vocabulary check and see if it’s suitable for the target audience.

Tom Johnson, a senior technical writer at Google, has an excellent example of clear instructions presented with the wrong terminology.

Johnson mentions his 10-year-old child, who is starting to cook and is fairly successful when instructions are clear.

However, when she has to sauté or julienne something, she doesn’t know how to proceed—even if she knows how to perform the action itself.

Similarly, he urges technical writers to consider the terminology when testing the instructions.

“For example, does a user know how to clear their cache, or update Flash, or ensure the JRE is installed, or clone a git repository? Do the users know how to open a terminal, import a package, cd on the command line, or chmod file permissions?”

So, when testing the instructions, you should go beyond the accuracy. The way you present the instructions is as significant to readers as the content itself.

Conclusion#

When you’re focused on describing the product, it can be easy to lose sight of customers for whom the documentation is written.

Fortunately, following the technical writing best practices we’ve seen will help you write great technical content every time.

Whether you’re writing API documentation or a user manual, you should keep these practices in mind.

That way, you’ll make reading the documentation an enjoyable experience and improve the customer perception of your product.