Product documentation is an extremely practical form of technical writing that product users access each time they have an issue to solve or a product feature to learn about.
Accordingly, technical writers and documentation creators need to take extra care when structuring product documentation and make it as accessible and readable as possible.
This article will provide you with six actionable tips to structure entire knowledge bases, as well as single documents so that users have no trouble finding exactly what they’re looking for.
Let’s start with our first tip.
Offer Quick Access to the Most Relevant Information
Since modern software products can be quite complex and not exactly intuitive to use, you’ll have to support your users in each phase of their journey and provide timely, easily accessible information exactly when they need it.
However, studies have shown that this kind of support often isn’t provided, especially in the B2B space.
Product users still find that they’re struggling to access important information which slows them down and makes them less effective.
So, how can you ensure that users have instant access to the product information they need to continue their work?
Well, above all else, it’s a good idea to present your documentation in the most accessible format—a dedicated documentation website.
Long gone are the days of pdf files stored locally on computers and printed instruction manuals people tend to misplace as soon as they get them.
These days, companies rely on dedicated documentation websites to offer uninterrupted, quick access to their product documentation so that users can get what they need in just a few clicks.
These sites are commonly hosted by documentation platforms so as you’re planning your product documentation, don’t forget to also pick the best platform for your needs.
Our own documentation software, Archbee, offers users the opportunity to create branded knowledge bases hosted in their own domain through AWS's CloudFront content delivery network.
That means your clients will have lightning-fast and ultra-reliable access to your product documentation whenever they need it.
But offering access isn’t the end of the story.
The users coming to your knowledge base will need specific product documents to solve their problems so you’re also going to need ways to provide them with information that’s relevant to their needs.
That’s where search engines come in, something your knowledge base really shouldn’t be without.
With an internal search bar, clients can easily look up their queries and find the articles they need to learn about a particular feature of the product or solve a specific problem.
Last but not least, as product documentation can get quite complex and cover a wide range of topics, it’s a good practice to offer quick access to the product documents users keep coming back to.
For this purpose, you can add a “Trending documents” section to the documentation homepage and update it continuously with the articles that are frequently visited.
Microsoft does this pretty well in their documentation:
Remember, quick and uninterrupted access to product information is the only way users can truly achieve success with your product.
Dedicated documentation sites that make information easily findable are your best way to provide that kind of access.
Decide on Your Preferred Topic Structure
There’s more than one way to approach structuring your product documentation. An easy way to start is to determine what kinds of topics you’re going to cover in your documentation.
Here’s a short rundown of the different topical structures you can choose that will later govern document production and the final look of your knowledge base.
The ideal topical structure will, of course, depend on the characteristics of your user base as well as the nature of your product.
Let’s see these topical structures in action to understand this logic better.
Product documentation organized according to product features is a good choice for products that have multiple, clearly differentiated features.
Complex, multi-functional CRM platforms are good examples of this. Have a look at the product documentation for HubSpot.
The product (HubSpot’s CRM platform) is divided by topic according to the features it offers.
So if a user is interested in documents, guides, or references for marketing, they would select the Marketing Tools section of the base and continue on from there.
On the other hand, if the product has a smaller number of functionalities, but a complicated interface users will be interacting with, it makes more sense to write product documentation according to the elements that can be found on that interface.
This is often the case with operating systems, design tools, or project management software, like Monday in our next example:
As you can see, the central concept here is the product’s interface itself.
The documentation details the specific functionalities the interface has. In our example above, the functionality that’s documented and discussed are the columns of the interface.
You can also focus on the user journey as the main topic of your product documentation.
That’s a good practice for documenting products that are complex to implement and users need how-to guides to accomplish different goals.
Stripe’s product documentation is often singled out as one of the best examples of useful, easy-to-follow documentation because it takes this approach very seriously.
Notice how the article titles represent different tasks the user might want to complete using Stripe. That’s a good example of a task-based topical structure.
Finally, some products have very different characteristics when you look at them from the perspective of different users who access them.
If you want to create documentation for end-users, administrators, developers, and other roles but keep it in the same knowledge base, you could try structuring the base in a way that navigates each role to the documentation written specifically for them.
Spryker’s documentation does exactly that:
Having a topical structure is important because it will make your documentation more consistent and guide your writing process once it’s time to create the content.
Therefore, before you do anything else, decide on the kinds of topics you want to write about and base your product documentation structure on them.
Focus On Solving One Problem With Each Document
On the subject of providing relevant and timely information, another wise practice to incorporate into your product documentation efforts is to make each article laser-focused.
To do that, you’ll need to boil each document down to a single problem to be solved.
And this makes a lot of sense.
As we already mentioned, users won’t be reading your documentation in a linear fashion, as you would a book.
Instead, they’ll access your documentation when they have a specific question or issue.
In that situation, you’ll want to provide them with straightforward instructions or a simple answer and not confuse them by throwing in an unrelated topic into the mix.
For example, look at how Slack’s product documentation first divides its entire space into a few key topics, such as basic usage, tool integrations, and app administration.
Those topics are then further boiled down into articles that provide “issue-sized” solutions to the very specific questions users might have when using the product (Slack).
Look at it from the perspective of the user. Say you’re a Slack user who needs to quickly find out how to integrate a work management tool (Asana, perhaps) into Slack.
In that case, you’d look up the article that does exactly that.
A single article that handles the topic of how Slack interacts with Asana.
Now, this article covers several sub-topics, such as how to install Asana, use it through the app, or how to disconnect it from your account.
These are all actions related to working with Asana within Slack.
What the article doesn’t do is deal with an unrelated subject, for example how to build a workflow in Slack. This issue represents a separate topic, covered by a different article.
That way, the user won’t lose any time learning about a functionality that doesn’t interest them at that moment and they won’t become confused or make a wrong assumption, for example that workflows are somehow related to tool integrations within the app.
Focusing on single problems in your documentation is the best way to structure your documentation because it allows users to find answers or instructions for the issue they have at that moment.
That way, they’re enabled to work efficiently with your product and will be coming back to the documentation every time they have a question.
Use Headings and a Table of Contents
In the last section, we talked about how every article should tackle just one problem, but there are ways to make each document even more focused.
The easiest one to apply is to divide the information in your document into logical sections, each one starting with a heading.
For best results, your headings need to be short and to the point, like in the example above.
There’s no need to use long sentences, just summarize the topic of the section in a couple of words and, if possible, show the reader what benefit the section will bring them.
For example, in the below screenshot from Customer.io, the reader is instantly informed what they’ll be able to do once they read the section in front of them:
Headings are an excellent way to improve the readability and scannability of your documents.
Instead of reading the entire document, the user can simply scan the headings and see if this is the information they have been looking for.
They can also scroll through the headings to find the section that holds the answer to the problem.
In addition to that, headings can help you put the information in your document into a logical order and reveal a hierarchical structure behind the information.
That’s a great feature if you’re writing instructions or product guides that have a temporal, step-by-step flow that needs to be followed to accomplish a certain goal.
For example, this getting started guide from Adyen uses headings to show the user how to proceed with creating an account and installing the product.
The headings are numbered and they represent the steps to be taken which are then further explained in the body of the section.
Finally, your headings can be isolated to form a table of contents for your document, which makes browsing, scanning, and reading even easier.
Quality documentation sites usually have a table of contents right underneath the headline or on either side of the page.
The best practice is to feature a table of contents that moves as the reader scrolls so they always have the option to jump from section to section in just one click.
Bear in mind that readers need navigational features to quickly find the answers to their questions within a document.
Headings and tables of content are some of the most useful features you can offer to make your product documents more scannable and readable, thereby giving the user experience a big boost.
Make the Document Layout Intuitive
Another tip for making the documentation more readable is to provide an intuitive layout that removes every obstacle and complication when a user is trying to find a piece of information.
There are a couple of ways to do this, but the most basic one is to break up the text as much as possible so that users can easily skip information they identify as unnecessary for their needs at that moment.
In plain terms, this means writing in short paragraphs of no more than three or four lines.
In the above example from Twilio, information is given in short bursts and every paragraph represents just one idea.
Readers instinctively know to skip a paragraph after the first couple of words if they come to understand it doesn’t contain the information they need.
One more great practice to follow here is to always put the most important bits of information close to the top, while everything else can be included later on, as the document progresses towards the end.
Writers sometimes call this layout the inverted pyramid of information.
This is actually a well-known writing hack in journalism where the news is presented in a way that prioritizes new information and places it at the top of the article, while background information and older news can be found closer to the bottom of the article.
The key takeaway here is that it’s not the best idea to make users read through large chunks of text that don’t directly relate to the need they’re having or the problem that they’re trying to solve at that moment.
A much better way to go is to make your document’s layout intuitive so that users can choose only the parts they need while leaving everything else aside for the next time they visit the document.
Use a Repeatable Information Structure
People are creatures of habit. If you provide your readers with a similar format in every article in your documentation, they’ll eventually get used to finding the same type of information in a particular location in your document.
Now, this kind of predictability might not be a good thing if you’re writing fiction, but it’s a very useful feature to take advantage of if you’re creating product documentation.
That’s because readers will always instinctively know where to look for a particular answer, making their usage of the documentation more efficient.
Let’s see how this works in practice.
Google Maps has a particularly user-friendly information structure.
The documentation always starts with an overview of a concept. In the following example, the article starts by explaining the Elevation Service feature:
The article then goes on to discuss the requests and responses of the feature in great detail.
After that, towards the end of the document, examples are given so that the user can understand how the code itself works.
That way, users of the documentation always know where they can find code examples if they need them and can open a document and skip right through to the end if they don’t need explanations, but just the code to implement the feature into their own work.
Making the information structure repeatable also helps technical writers with the document creation process.
It allows them to create templates for various types of documents where bits of information are always found in the same place.
With a good template on their hands, they have an easier task writing documentation because they don’t need to contemplate which information goes where.
Here’s an example of a great template that guides the writing process from beginning to end.
The ability to know where to look for a piece of information is another hallmark of efficient documentation structuring.
When creating your documents, don’t try to be too creative with the writing and instead follow a repeatable information structure so that your readers can find what they need easily.
Conclusion
A key concept we discussed in this article is user experience.
In order for your product documentation to serve the needs of your clients, it needs to be easy to use and provide the right information at the right time.
Every tip we shared here will bring you one step closer to a product documentation structure that’s intuitive, easy to use, and helpful to your readers, so try your best to apply some if not all of them in your documentation process.
The reward of satisfied, successful users will definitely be worth the trouble.
