Creating documentation without a clear structure in mind is like buying random ingredients without a recipe.
The importance of documentation structure
Most people disregard the importance of documentation structure, and tend to only focus on writing down everything related to their product. This may be enough to avoid legal issues but not enough to create engaging and informative content.
Let's imagine this situation: You have a shopping mall. It has all the usual things a shopping mall needs:
- Shops
- Food stalls
- Information booths
- Toilets
Now let's imagine we just haphazardly throw everything into our imaginary shopping mall. We could very easily end up with a layout where all toilets are on the roof, or a food stall somehow ends up in a clothing shop.
While we rarely see the above example happen with malls, I've experienced, on numerous occasions, the same thing happening to documentation, providing a horrible user experience to readers. This can result in a great number of customer tickets asking for information that might be available in the documentation, but users either cannot find the information, or they get so frustrated that they don't even try.
A logical structure can enhance user experience, reduce the number of customer tickets, and even reduce churn in some cases. Of course, structure can only get you so far. Without well-written content, no amount of (re)structuring will save your product.
 |
|---|
| A mall having the same structure as documentation |
How to structure documentation in an engaging way?
Unfortunately, there is no ultimate truth readily available to answer this question. Just like all products (although documentation is a product as well), each documentation is different. Be that as it may, we can still rely on some general guidelines:
- Providing a high-level overview of the product
- Drafting a user journey
- Grouping information
- Creating entry points
- Connecting sections
Providing a high-level overview and drafting a user journey
Providing a high-level overview and drafting at least one user journey should be the first thing one considers when creating a structure for product documentation. The high-level overview serves as the entry for new users and an introduction, and it's one of the most important things to consider. Remember, you can only make a first impression once! If the first impression of your product is that the documentation is little more than an afterthought, it can shine a bad light on the entire product itself.
You should introduce the product to the users in a short overview. This overview should showcase some of the most important functionalities and how the users can benefit from them. Don't go into too much detail. You will have plenty of time to do that later on. It could also be a good idea to have an illustration to either explain the product or the user journey the documentation will guide the users through.
After a brief overview, the next thing to consider is the user journey. If you either don't have the resources or the product maturity to have multiple user journeys, have at least one user journey, which assumes that the user reading the documentation sees your product for the very first time. Ask these questions from yourself:
- What do I want the users to see?
- How can they achieve what they want?
- How do I best showcase what our product can do?
By answering the questions above, you will get a general idea about the user journey and the direction you would want to guide your users toward.
Grouping information, creating entry points, and connecting sections
Now that we have the overview and at least one user journey, the next step should be to align and group the existing information to best serve our user journey(s). This part, again, is unique to every product. Still, I will list some pointers on how to group information:
- Based on the user's business maturity
- Based on products, if you have multiple products in the same ecosystem
- Based on complexity
- Based on when the user will most likely first encounter that part of the product
- Based on categories, such as objects for APIs
After grouping information, you should create an entry point for each. An entry point should serve as a short introduction and possibly as a crossroads before a branching path from where the user can go to a specific part of the documentation best suited to their needs. It's also important to set the tone and complexity of the category. Avoid bait and switching! If a category is aimed at experienced users, it shouldn't explain trivial matters as they will just get bored and move on to something else, possibly missing valuable information. On the other hand, if the target audience of a category is managers or business owners, you should focus on what values the product will add to their business instead of explaining the nitty-gritty parts.
Lastly, just like with malls, it's important to create "routes" between categories to ensure that users can conveniently see how different functions are connected in your product and to enable them to move between categories easily and logically. You can achieve this with notes, hyperlinks, footers, or really in any other convenient way.
If you would like to check out an example, see my Documentation example.