Excellent product documentation is non-negotiable in today’s software market.
Such documentation serves as a connection between the business and its customers.
It provides all the necessary information about the product or service, acts as a promotion tool, encourages customers to dive deeper into the features of a product, etc.
In short, you’ll be hard-pressed to find a business that wouldn’t benefit from top-notch product documentation.
In this article, you’ll learn how to create it by following a few essential tips.
Let’s start!
Make a Document Style Guide
A company that wants to produce high-quality documentation for its products shouldn’t leave the writing process to chance. Having a style guide ensures that this doesn’t happen.
When technical writers have a style guide, they have a resource that provides instructions on how to create the documentation.
That means that every document from every writer will be consistent.
That doesn’t mean documents must be rigid, boring, or without personality.
George Lewis, an experienced communicator, explains that the purpose is to simplify the process of creating documentation.
The style guide defines the language to be used. Defining this early on ensures that consistent, unambiguous words and phrases are agreed, making the production and review process simpler.
But what does “defining language” mean in the context of product documentation?
One of the things it refers to is company style and branding. For instance, Mailchimp has a style guide where they instruct their employees on how to write about the company.
As you can see above, that includes, for example, how to spell the company name, which changed over time.
Furthermore, a style guide is also important for forming a connection with the customers, as Nicola Evans, a product content expert, points out.
In other words, a style guide allows you to communicate with your customers more effectively.
How so? Let’s look at the Mailchimp example again.
It’s a marketing platform and email marketing service aimed at small businesses with millions of customers, as their team points out.
Therefore, they can assume that the audience for their product documentation is broad, coming from various industries and with different levels of technical knowledge.
That’s why they instruct their writers to write clear, useful, friendly, and appropriate content. It’s all about reaching the most readers possible, as you can see below.
Mailchimp’s style guide also covers other topics, like formatting, structuring content, standardized spelling, etc.
However, the point isn’t that you have to copy their philosophy and approach to the customers.
You know your audience best, so simply write in a way that works best for them, and rely on the style guide to ensure that your documentation is consistent in terms of form and quality.
Add a Table of Contents
One of the characteristics of top-notch product documentation is that it’s easy to navigate.
That means it can be helpful to customers, and getting helpful information is why customers turn to product documentation in the first place.
Having a table of contents is crucial to creating documentation that’s easy to navigate.
It’s basically a birds-eye view of the information available in the document, with the headings and page numbers of each section, like in the example below.
However, since today the product documentation of SaaS businesses is almost exclusively online, the table of content looks somewhat different and, more importantly, is even more functional.
How? Well, in addition to laying out the contents of your document so that the customer can quickly scan them and see if they’ll find what they need, you can turn the headings into links.
For example, Shopify has a table of contents for the whole documentation on the left-hand side, as well as the one for every page of their documentation specifically:
That way, the readers can see if the information they’re looking for is on that page as soon as they open it.
The table of contents for a specific page doesn’t necessarily have to be front and center, like Shopify’s is.
For example, you can position it on either side of the main text.
Take a look at the example from Dashlane’s documentation below. The table of contents is on the right-hand side.
Of course, it’s clickable, so the navigation for the users is as simple as it can be, which significantly contributes to the overall quality of the documentation.
Also, it’s worth mentioning that Dashlane’s table of contents stays on the screen the whole time. For instance, you can scroll down to step 3, and the table of contents will still be visible.
As you can see, a table of contents can be a very valuable element of product documentation when finding information.
Be sure to include it if you want your documentation to meet the highest standards.
Format Content Using Headings
As we mentioned in the previous section, the way you organize information is key to making sure your product documentation is truly outstanding.
If you take our advice and add a table of contents to your document, then headings should follow suit.
Headings are a great way to make your document more readable and approachable for your audience.
Essentially, they divide a long piece of text into smaller sections.
For example, you can use headings to divide the documentation into main sections and then use subheadings inside those sections to divide the text into even smaller sections.
Below, you can see an example from Dropbox’s documentation.
As you can see, the section deals with changing and resetting the password.
The document is formatted so that under one main heading, there are three subheadings.
One provides instructions on how to reset the password from the sign-in page, the other on how to do that from the settings, and the last section is about possible issues with changing the password.
Formatting your documentation with headings and subheadings significantly improves its usability—just imagine what the text above would look like without them.
Would it be readable? Sure, if it’s well-written and informative.
However, it would be much harder for users to navigate and find the information they need without reading it from beginning to end.
But the readers aren’t the only ones who benefit from using headings. As David McMurrey, a technical writing expert, explains, documentation also helps writers organize their work.
Headings and subheadings make writing easier by focusing on one topic at a time and building a hierarchy within the document.
So one broad topic, like changing the password, can be parsed into several smaller elements.
All of that makes it easier for authors to organize their writing, which helps the readers follow it and understand it more easily.
Include Instructional Images
Reading product documentation isn’t the most exciting activity imaginable.
You can have fantastic writing skills, but the truth is that the readers come to the product documentation to solve problems or learn about the product, not to derive pleasure from reading.
Product documentation has a clear purpose, and you should do whatever it takes to fulfill it if you want to create top-notch documents. Using instructional images can help you with that goal.
How? By communicating information quickly and clearly.
One look at an image, and a reader can get information in a fraction of the time that it would otherwise take them to read a written explanation.
That’s also why Tom Johnson, an experienced technical writer and blogger, is a big proponent of visuals in documentation.
The importance of quickly transmitting information shouldn’t be underestimated.
As we mentioned, users go through product documentation to find a specific piece of information they need, which usually means they’re not interested in reading any longer than necessary.
According to research by Chartbeat, a lot of them stay on the webpage for less than 15 seconds.
That means that you need to be efficient in providing them with information.
Luckily, images are a great way to do that.
Product documentation can include a variety of media, including videos, GIFs, graphs, images, etc. Screenshots are especially convenient and useful.
With screenshots of your product, you can easily demonstrate your written instructions, so the readers can see more easily how something looks in practice.
For instance, below, you can see how Asana uses screenshots in their product documentation.
They illustrated how to edit roles on the project in their project management tool.
As you can see, they used numbers on the screenshot and explained underneath the screenshots what each number represents.
That’s a simple way to clearly show readers where they can edit roles and what each option means.
Using instructional images like that can raise your documentation to a higher level of quality and usability.
Proofread Your Writing
If you want product documentation you can be proud of, proofreading is a practice you shouldn’t neglect.
Proofreading can help you accomplish several goals with your writing, which are all related to making your documentation more accurate and enjoyable.
Simply put, with proofreading, you detect the issues in the text so you can polish and edit it.
What does proofreading include? In essence, everything regarding effective and accurate communication, as this definition from W3schools explains:
Proofreading can be defined as the process of correcting and approving errors in writing, such as grammatical stuff, spelling checks, and proper implementation of punctuation, technical arrangements as well as other verbal communication mistakes.
However, when you spend a long time creating something, it can be challenging to proofread it with fresh eyes.
Luckily, there are simple methods that you can use to make that practice more effective.
One of them is to listen to it, as this writer advises in his Twitter post.
How to listen to it? The easiest way is to read it out loud.
When you do that, you can catch errors, wrong sentence structure, and other undesirable elements in your writing, as Paula Peters, a long-time technical writer, puts it.
Of course, if you don’t prefer to read it out loud or give it to someone else to read it to you, which is also an option, you can use various tools to help you with proofreading.
For instance, you can create a proofreading checklist or get one from various sources online.
Below, you can see a part of such a checklist from Techwhirl.
As you can see, the purpose of it is to remind you what to look for and keep you accountable for the quality of your writing in the process.
And when it comes to grammar, spelling, punctuation, and all the language-related needs, Grammarly is a great tool that you can use for proofreading.
It highlights mistakes, offers corrections, and gives suggestions regarding sentence structure and the tone of your writing.
To sum up, proofreading your writing is an important step in your way to creating top-notch documentation.
Whatever tool or method you use, it will result in high-quality documentation that will accompany your product well.
Keep Product Documentation Updated
Your products are a constant work in progress, and the documentation that goes along with them should follow suit.
If you want to provide customers with a resource of information for your products or services, their documentation should be updated just as frequently as they are.
Imagine what a customer would think if they saw a new feature just to find that the product documentation was last updated six months ago.
That certainly wouldn’t be a model of professionalism and care for the user.
Of course, sometimes it’s hard to keep track of all the changes and updates you and your team should make.
That’s why some writers find it helpful to set reminders for updating documentation.
That can be as simple as using a Google Calendar or other similar tools, but you can also utilize an automated bot like the one used by Government Digital Service.
They named it Daniel the Manual Spaniel, and its function is to remind the writers via Slack to update the documentation.
You can also use it because they made its code available to anyone on Github.
Regardless of whether you use a bot, a calendar app, or post-it notes, once you update your documentation, you should inform your customers about it.
That way, you promote new features of your product or service and simultaneously make it easier for them to learn more about it by showing the latest information to them as soon as it’s available.
For instance, Firefox recently introduced a new feature called Firefox view, so they announced it in their release notes.
Also, they linked to the new article in their product documentation about the Firefox View.
That way, users were informed of an exciting new feature and provided with a source of information about it at the same time.
If you want to maintain product documentation to the highest of standards like that, it’s important to have the right tools.
For instance, if you create your documentation in Archbee, you can easily check when the document was last updated and who updated it.
You can even assign a team member to be on top of updates.
That’s a great way to ensure that your documentation doesn’t fall behind and that your users always have a reliable resource.
If you provide them with that, they’ll be more likely to show their appreciation by staying loyal to your business.
Conclusion
Creating the best possible product documentation takes time and effort, but it can pay off in the long term.
Having high-quality, comprehensive, and useful documentation that accompanies your product or service is a great way to keep customers happy and attract new ones.
We hope this article helped you by providing you with ideas and tips on how to create product documentation that will be an impeccable resource for all your customers.
