User documentation can be a valuable source of information for your customers, providing them with support and knowledge that improves the whole experience of using your product.
But that kind of user documentation isn’t easy to create.
A lot of time and effort is needed to write user documentation with those qualities. Also, that task can be even more challenging without following certain guidelines.
That’s why we bring you the best practices you should implement to create top-notch user documentation.
Read on and find out more!
Know Your Target Audience
To produce the best user documentation possible, one of the crucial elements is knowing who you’re writing for.
Knowing your target audience can determine what topics you’ll elaborate more on, how you will write, etc.
In short, how well you know your audience can determine whether the user documentation will fulfill its main purpose.
You probably know what it is, but let’s refresh our memory for a second with this definition from David Oragui:
User documentation guides your customers, helping them to use your product properly while also assisting them with any difficulties that arise.
In other words, user documentation needs to be helpful for its audience, and you can make it that way only if you know who they are.
However, as H. Allen Brizee and Kety A. Schmaling from Purdue Online Writing Lab indicate, it’s not a one-size-fits-all situation.
Considering that, let’s see a couple of examples of how writing for different audiences can produce different results.
For example, Shake is a tool for reporting bugs and crashes in apps. It’s used by developers, software engineers, and others involved in software development.
Therefore, user documentation for Shake is written with that technically-savvy audience in mind, so it contains parts like the one below.
Someone without that technical knowledge most likely wouldn’t be able to understand most of it.
And that’s perfectly fine because the documentation is tailored to Shake’s target audience, which is familiar with the terms the writer used.
On the other hand, writers that create documentation for Jira, a project management tool, have a different target audience.
Jira is a tool for teams collaborating on projects in various industries. However, it targets teams that work in Agile, a specific approach to project management.
Therefore, user documentation for Jira is tailored to an audience familiar with terms and phrases like Scrum, Kanban, backlog, and sprint.
The point is that a writer should know what their target audience looks like because the effectiveness of user documentation depends on how well the writer can adjust their text to their readers.
Only when they identify their target audience can they reduce the risk of creating unhelpful and incomprehensible documentation.
In other words, documentation that would completely miss the mark.
Create a Logical Documentation Structure
When creating user documentation, you should make sure that you structure it logically. Simply dumping heaps of information randomly into the document won’t benefit anyone.
Documentation structure is vital for its usability.
Best user documentation is arranged in such a way that a user can easily navigate it, scan it, and find the piece of information they are looking for.
Because it doesn’t matter if your writing skills are sensational and you pour your heart and soul into the user documentation if the structure makes it hard for the user to find what they need.
Users simply don’t sit down with a how-to guide to read it cover to cover.
Here’s some data about how much people read on a website: according to Jakob Nielsen’s analysis, on average, they read about 20% of the text on a webpage.
Therefore, it’s imperative that, when they open the user documentation, they find a logical structure.
For starters, a table of contents can be of great help. It’s a list of sections in your user documentation, and a user can see where to find the information they are interested in.
For example, Fitbit has user manuals for all its products and software, and every manual has a table of contents like the one below.
As you can see, it contains very descriptive and clear headings and subheadings, which is another helpful element.
Also, considering that it’s in the browser and not on paper, a table of contents can make navigation even easier if you make the headings and subheadings link to the related section, which is how Fitbit’s documentation works.
Creating a logical structure also means starting with the more basic information and working your way down to the advanced features.
You don’t want to confuse your reader with something too complex before they even grasp the essentials of your product.
Trello does that very well in their documentation. They organized their guide in nine steps.
As you can see, the steps follow a natural learning curve. First, users learn the Trello board basics, how to create their first project, etc.
In the end, they are familiar with the product enough to adjust admin controls, learn about the Premium version and browse tips and tricks.
That’s well-structured documentation that allows logical progression, making it an immensely helpful resource for the users.
Write Using Plain Language
One of the essential skills a technical writer can have is the ability to convey technical information to the reader using plain and simple language.
User documentation that is incomprehensible to the target audience simply won’t accomplish its goal—to communicate the information and solutions the reader is looking for.
Tom DuPuis, an experienced technical writer, advises that a writer should always ask themselves one question:
Although that sounds simple, that question is the core of what a writer should aim for when creating user documentation.
So, how to write in plain language? There are a few elements that can help make documentation more approachable.
First, you should avoid using industry jargon. If your audience doesn’t have a high degree of technical knowledge, specific terminology could be foreign to them.
However, it isn’t always possible to eliminate jargon completely. In that case, make sure to explain it to the reader, as Kyle Wiens and Julia Bluff advise.
If you absolutely need jargon, do your best to provide context, short definitions, or even a glossary of terms.
For example, you can provide definitions of your product or service’s terminology.
Below, you can see how Charthop did that in its product documentation.
As you can see, they have a whole chapter about terminology, and on the right-hand side, you can see the terms they defined.
That way, they minimize any potential confusion among their users by providing them with a resource that defines terms in a clear way.
And using plain language is beneficial regardless of your target audience.
They can be complete beginners or have prior knowledge, but they’ll appreciate simple and approachable writing.
For instance, even more complex documentation, like the Vimeo API reference, can be written that way.
Even if you know nothing about API, you can understand the sentences underlined above.
The relaxed tone and straightforward way of writing can be implemented in creating the documentation for any product.
That will only make it more usable and engaging, which are qualities every technical writer should aim for in their documentation.
Include Media to Improve Comprehension
Different types of media can be a great addition to your user documentation, and they’re especially useful for improving comprehension, something that technical writers should keep in mind at all times.
Of course, the text should be the central part of the documentation, as it’s the primary way of presenting information. However, that doesn’t mean it should be the only way.
Adding visuals, particularly screenshots and videos, can enrich the documentation and, in synergy with text, provide an excellent experience for the user.
As Kesi Parker, a technical writing influencer, puts it, they should complement each other.
But how can adding media improve comprehension if the writer puts all that effort into creating an informative and understandable text?
It’s simple. Media adds another way to present information, and some information is just easier to comprehend and absorb visually.
Monday, a project management platform, illustrates that in their user documentation.
You can see how they use text and a screenshot to give instructions to the user.
First, they use textual descriptions of the steps the user needs to take to add a workdoc.
However, they also include an annotated screenshot to show precisely where to click on the page and which option to choose to complete that task successfully.
They also liberally use GIFs, another form of media that’s immensely helpful in improving comprehension.
For example, one GIF can condense many words and paragraphs of instructions into just a few seconds and help you avoid using too many screenshots.
However, videos are unbeatable when it comes to visually presenting a large amount of information in the shortest amount of time.
For instance, even if the user isn’t in the mood to read instructions, they can always find 45 seconds to watch an instructional video like the one in the Whatfix documentation.
As you can see above, the video about installing the Whatfix Editor is at the top of the page, and it shows the necessary steps.
However, there are written instructions and a screenshot under the video. The writers have clearly covered all the bases and ensured that the information is presented in a variety of ways.
That’s the point of including media—it can only add to the quality of your user documentation by offering different ways to learn about your product.
Make Your Documentation Searchable
Documentation can be useful for users only if they can find it and if they can easily find what they need in it.
Ensuring that your documentation is searchable needs to be among your priorities if you want to have the best possible user documentation.
Let’s first consider how a user even finds themselves in your user documentation.
One of the ways is to go to your company’s or your product’s webpage, find the product documentation, and then browse through its contents until they find what they’re looking for.
The other way is to open Google and type a question in the search box.
Which do you think is more common?
According to an example from Hallam, a digital marketing agency, only about 35% of visitors land on a homepage. The rest land on specific pages.
Although their example is for the website about sandwiches, the same principle applies to user documentation.
You can check where your visitors land with Google Analytics, and, most likely, a significant percentage will be distributed among specific documentation pages, on which the users land through Google.
That’s why it’s crucial that you make your user documentation discoverable on search engines.
For instance, when a Spotify user wants to find out how to install that app on a Smart TV, the first result is a link to Spotify’s user documentation.
And when they click on it, the link leads them to Spotify’s support page, where they can learn the answer to their question.
For results like that, you should create your user documentation with tools like Archbee.
In Archbee, you can make any document you like discoverable on search engines by simply enabling that option with one click.
Archbee also has SEO Meta Controls that allow you to improve the SEO performance of your documentation. In other words, you can optimize your keywords, change the URL, write a meta description, etc.
Furthermore, as we’ve mentioned, your documentation should be searchable once the user is in it.
The simplest way to ensure that is to have a search bar where the user can enter a keyword or a phrase and find relevant information.
Archbee has a robust search function that shows results by going through all the titles and every piece of content in the documentation.
For example, if you want to know how to integrate Pathfix with Stripe, you can find that in their documentation in no time.
To sum up, if your users can find your documentation on search engines, they will visit it much more often.
If they then can use a search function in it, that level of convenience will make them use it whenever they have a question or an issue.
Conclusion
Writing user documentation of the highest quality certainly isn’t a walk in the park.
However, while it is challenging, it isn’t impossible.
If you follow the practices described in this article, you’ll undoubtedly increase the quality of your user documentation.
Knowing your target audience, creating a great structure, using plain language, enriching the text with various forms of media, and making the documentation easy to find and search are all crucial for great results.
Start implementing these practices, and you’ll soon see excellent results.
‍
