Alice has just joined a new team as their sole technical writer, and she has been tasked with documenting a new product or software from scratch. She stares into her computer screen, unsure of where and how to begin.

For many technical writers —like Alice —figuring out documentation structure can be a source of initial confusion and overwhelm. What should you document? How should you document it? And, where should things go? Once you figure out structure, you'll have a sense of direction; once you have direction, everything's easier to start.

Structuring docs can be a very nuanced problem, and there's no one-size-fits-all that all software documentation projects can adopt. Regardless, no matter what approach you take, at a very high level, your documentation should be categorized logically, such that it intuitively answers 'where can I find information on how to do something?' for users and 'where do I put new information?' for other technical writers and contributors.

For me, two things I do to get a jump start on structure are follow common patterns of similar documentation projects and use templates for individual pages.

Follow common documentation patterns

The reason behind this approach is simple: your users are not isolated. They've most definitely used and consulted several documentation and have grown accustomed to specific patterns and expectations. Don't try to reinvent the wheels and structure your docs differently. You'll only confuse your users and make it more difficult for them to find the answers they need. Look at projects that are similar to yours. How have they structured their documentation? Are there any similarities with your product? What can you copy? And, what can you improve?

Here's a basic structure I usually start from and then build on:

1. About the product: Brief introduction of the product covering what it does, who it is for, the pain point it helps users address, e.t.c. Many people will come to your docs to figure out what the software does. Someone will mention it, or they'll google a phrase randomly. You should explain what your software or company does and why it exists.
2. Setup and installation: This does not need much introduction. What does one have to do to get up and running with the product or tool?
3. Getting started tutorial. This tutorial should cover how to complete the single smallest, most common, or most important workflow for which users/developers use the product for. For a product like Notion, this could be something like creating your first page. For something like Barter, it could be sending USD from your Nigerian naira account. And for something like Stripe, it could be how to set up a simple checkout page to accept online payments.
4. The rest of the documentation: The rest of the documentation can then either be categorised and split by target audience or use cases, features, or a combination, based on what works for your project.

• Usecases: Building on the getting started guide, the rest of the docs can be categorised into instructions or guides on individual tasks that users can accomplish with the software and how they can do so. For example, for a product like Buycoins, you'll be looking at other things that users can do on Buycoins to achieve their goals — things like withdraw funds, deposit funds, trade peer to peer, e.t.c
• Features & Concepts: You can also decide to categorise the docs based on the different features of the software and how to perform various tasks with them. This is more relevant for SaaS products. For example, something like Notion has individual features like widgets, tables, databases, e.t.c. You could categorise your documentation per feature: what each feature is, when users may want to use them, and how users can complete various tasks with each feature (e.g: add a widget, remove a widget, build their own widget), e.t.c.
• Audience: You can also decide to group your docs based on different user profiles and features or information that is most specific to them. For example, some products are intended for use by end-users, developers, and designers too. This approach is adopted by the Readthedocs docs.

5. Resources: This section can contain community-contributed materials, projects, tutorials, examples of others using your product, e.t.c

6. FAQs

Use Templates

If you've figured out the structure of the entire documentation as a whole, the next thing you need to figure out is the structure of individual pages and different categories of content. Templates provide question checklists to show writers what information they should include, so they don't have to guess.

Using templates solves two problems. First, it enforces standardization (i.e., each page has the same structure) and so lowers the time it takes for users to search through documentation. The second reason to use templates is that it helps you and other contributors to quickly overcome the blank page dilemma.

Here are some resources you should check out to learn more about different document pages types and also see some established templates:

• The Good Docs Project
• GitLab Documentation Topic Types
• Gatsby documentation types and templates
• Divo documentation guide

Conclusion

Just naming things in programming, documentation structure isn't the easiest thing to figure out. I hope this article provides you with a starting point from which you can evolve.

Further reading:

• Defining an efficient documentation structure