Mistakes to Avoid When Creating User Documentation

User documentation comes in various shapes and sizes, but the best examples have one thing in common—they avoid the mistakes we discuss in this article.

When creating such an extensive and complex resource as user documentation, which so many people rely on for information, it’s easy to make an error here and there.

However, there are some major mistakes that can significantly impact the overall quality of your documentation.

Let’s dive right into the first of the most egregious mistakes you could make.

Not Making Documentation Easy to Find#

Most users will look for your documentation when they have a pressing need or problem to solve and need the information quickly.

That’s unsurprising, given that the main purpose of user documentation is to provide an accessible resource of knowledge about a product.

Therefore, users count on the documentation to fulfill that purpose.

So, how can you make access to the documentation as quick and straightforward as possible? Make it easy to find.

As Adam DuVander, a technical content specialist, sums it up, there’s no difference between a document you can’t find and one that doesn’t exist.

Illustration: Archbee / Data: EveryDeveloper

For example, if your users need to scroll up and down your website without any indication of where to find the documentation, that’s not ideal, to put it mildly.

That’s the case with the website of PCCW Global, a big information and communication technology company.

They provide a range of communication, voice, and data solutions, yet the "Resources" tab contains only brochures, case studies, and promotional videos.

Source: PCCW Global

However, although you can’t find it anywhere on their homepage, there is a user guide for PCCW Global.

You can find it with Google’s help.

Source: Google

But that’s not all.

There is a more comprehensive user documentation resource for one of their products, with guides, API documentation, and everything else you need to use the product successfully.

Source: Console Connect

Where is it? On the Console Connect website.

How can you find it? Only if you click around the PCCW Global website and encounter this pop-up notification.

Source: PCCW Global

Sure, Console Connect is also referenced on the PCCW Global homepage, but without any indication that services are moving there, as this notification informs you.

That can easily confuse a user who just wants to find the documentation about PCCW Global and its products.

There are no such resources on the homepage, but you could find some if you Googled them.

Also, there is much more documentation on a different website that you’re more likely to stumble upon than find on purpose.

A situation like that can frustrate users and waste their time.

If you want to keep your users happy, don’t make them search through multiple channels to find what they need.

Not Considering the Ease of Navigation#

Your users shouldn’t take long to find the information they need in your documentation.

Once you ensure your documentation is easy to find, you also want to provide ways to navigate it effortlessly.

One of them is a search function.

A simple search bar can save your users a lot of valuable time; if they want to find information, they only need to type in a few words, and a relevant document will appear on their screen.

Although the search feature in the documentation is already widely accepted, some companies still make the mistake of not including it.

For instance, Telegram, a popular messaging platform, provides detailed user documentation with useful information, both for beginners and the more technically-savvy users.

Source: Telegram

Above, you can see part of Telegram’s API documentation page.

However, no matter how long you focus on that screenshot, you won’t find one thing—a search bar.

There isn’t one on any other documentation pages either, like the FAQ for advanced users.

Source: Telegram

That means Telegram users need to read through the whole webpage to find what they need or use keyboard shortcuts to open a search box in their browser.

In other words, by not including the search bar in your documentation, you’re sending a message to your users that you haven’t created your docs with their convenience in mind.

In addition to the search function, the ease of navigation can be significantly improved by including a table of contents.

Let’s take a look at Basecamp’s user documentation page:

Source: Basecamp

When you land on it, you have everything you need for easy navigation—a search bar and links to every type of content created for users.

If you follow any of the links, it’s clear that easy navigation was among the Basecamp team’s priorities.

For instance, below, you can see the first page of the “Getting started” guide.

Source: Basecamp

On the left-hand side, there’s another search bar and a table of contents showing you which guide you’ve opened.

The main part of the page is essentially a detailed table of contents for this particular guide.

Those elements that make navigation in the documentation easier are essential for user documentation.

Jonathan DeVore, who works with teams that want to provide better customer experience, explains it like this:

Illustration: Archbee / Data: Screensteps

In other words, users want to read the specific pieces of information they need, not every word you and your team wrote.

Making navigation in your documentation easier will allow users to find what they need.

Assuming the Users’ Level of Knowledge#

Do you know who your users are?

Most likely, you can assume the profile of people most interested in your product, but do you know their backgrounds, knowledge levels, interests, and industries they work in?

The range of the users’ knowledge levels can be especially wide in the software industry.

Regardless of the type of software product and its use, the users can come from all kinds of different backgrounds.

Elizabeth Garcia, a product marketing manager at Pandium, points that out:

Illustration: Archbee / Data: Pandium

So, how can you create documentation that will be valuable for such a diverse user base?

The safest way to make your documentation as helpful as possible is to avoid assuming how knowledgeable your users are.

Even if you’ve done your research and know that most of your users are, for example, developers, you still shouldn’t assume what they know and what they don’t know.

For instance, some developers are fresh out of college, and some have 25 years of experience. Naturally, they don’t have the same level of expertise or skill sets.

That’s why you should make sure your documentation is easy to read, using plain language and avoiding technical jargon as much as possible.

Take a look at the part of Amazon Alexa’s Voice Service documentation below. It’s intended for developers, but you can read and understand it without issue even if you’re not one.

Source: Amazon

That’s because the writers started this documentation with a story, providing context instead of immediately jumping into technical details.

Developers can learn how their product can integrate with Alexa and think about some vital questions about their product’s design, interaction, and use.

All of that can help them integrate their product with Amazon’s successfully.

Avoiding technical jargon like in the example above is recommendable, but the reality is that it isn’t always possible.

When there’s a situation where you need to use technical terms, ensure that your users know their meaning.

You can do that with a glossary of important terms, like the one from Daraja, a developer portal of mobile network operator Safaricom.

Source: Safaricom

Providing a glossary of essential terms can ensure that your users can look up an explanation if they encounter something in your documentation that they’re not familiar with.

Keeping the language of your documentation simple and understandable while also providing explanations for technical terms is a great way to account for a wide range of your users’ levels of knowledge.

Neglecting to Include Visual Content#

Creating user documentation doesn’t necessarily mean only focusing on writing clear and concise information.

On the contrary, presenting your documentation only in the form of text is a mistake that can be detrimental to user experience.

Visuals are also a vital part of high-quality user documentation.

They can efficiently illustrate complex concepts, provide straightforward instructions, make it easier for readers to focus on the docs, etc.

That’s only a part of their advantages. The fact is that the human brain is wired to process visuals with ease, and data supports that.

According to research by MIT, it only takes a fraction of a second for a brain to fully process an image—more precisely, between 13 and 80 milliseconds.

Illustration: Archbee / Data: MIT

Therefore, instead of describing something in writing, it’s a good idea to use screenshots, images, graphs, videos, charts, or other types of visuals, depending on your needs.

What can happen if you neglect visuals? Take a look at Cheddar’s documentation below.

Source: Cheddar

There aren’t any visuals in the part of the documentation you can see above, but that might seem like a minor problem because there also isn’t a lot of text.

However, the situation is different when you encounter the wall of text further down the page.

Source: Cheddar

That’s a situation where some sort of visual would break the text up and make it easier for readers to follow.

The situation is the same throughout Cheddar’s entire documentation— there isn’t a single visual in it.

Some might argue that this is an example of API documentation, so it’s more technical and less appropriate for colorful visuals.

The type of documentation doesn’t have to be an excuse to neglect visuals.

Take a look at Spotify’s API documentation below:

Source: Spotify

As you can see, they included a bulleted list, and their code examples are visually attractive and stand out from the rest of the text.

Those two visual elements alone make the documentation much easier on the eyes and more inviting.

There is more. Spotify also includes screenshots in the same API documentation.

Source: Spotify

Screenshots can be particularly useful for providing instructions, as they show the actual screen and the elements on it.

That way, users can know at all times if they are following the instructions correctly.

Neglecting visual content like that isn’t a mistake only for aesthetic reasons.

In addition to making docs more appealing, they also make them more understandable and accurate, and those are essential features of every great user documentation.

Forgetting to Update the Documentation#

One of the biggest mistakes you can make with your user documentation is not updating it.

Why?

Because if you don’t update the documentation, it will turn from a valuable resource to a collection of outdated information that just takes up space and, worse than that, alienates your users.

Your users don’t have endless patience and loyalty, especially when they know they can look for other software solutions for their needs—solutions with relevant documentation.

In other words, your documentation should reflect every change your product goes through.

Incomplete and outdated documentation is a surefire way to annoy your users and risk losing them.

The minimum you should do for your customers is to warn them if some version or part of your documentation isn’t updated.

For example, Medium has detailed developer documentation on GitHub, but before developers dive into it, they are informed that it isn’t supported anymore.

Source: GitHub

However, remembering to update the documentation as soon as the product changes can be challenging.

Other responsibilities that you and your team members have can get in the way, and the documentation could end up forgotten on the pile of to-do tasks.

To prevent that from happening, you can set up reminders.

For example, technical writer Svetlana Novikova described in her blog post how her team used Slackbot as a reminder to update their docs every Monday.

Source: JetBrains

Dedicating a specific time for updating documentation is an excellent way to make updating a process and not just a task you’ll get to when you have the time.

In addition to dedicating time, another great idea is to dedicate a specific person to updating the documentation.

For instance, if you use Archbee for your user documentation needs, you can select a member of your team, and they’ll get recurrent notifications to check the documents.

Source: Archbee on YouTube

That way, you know that someone is responsible for updating the docs and that, even if they forget to do it, Archbee will remind them.

Conclusion#

When it comes to user documentation, it’s important to get it right.

After all, user documentation is a resource that aims to help, teach, and inform every one of your users, from a beginner to an expert, about every facet of your product.

That’s quite a task, however you look at it.

Luckily, now you know which crucial mistakes you should avoid to create documentation that is up to the task. Your users will be thankful for it.

Try Archbee's full range of features with our free 14-day trial.