Whether you’re creating API docs, product docs, FAQs, technical guides, onboarding docs or a mixture of them all, here’s how you build a structure that makes them easy for customers to use
Last updated
Was this helpful?
Was this helpful?
What matters more: the structure of your documentation, or the information contained within it?
You might be inclined to say that it’s the content of your docs that should take priority. And you’re right! But structure is just as important — because no matter how incredible the info in your docs is, it’s only useful to users if they can find it when they need it.
But don’t worry. Building a solid documentation structure can start at any time — whether you just have API reference docs, or you document your product and API, offer guides and tutorials, and also need a home for your changelog and help center.
In this guide we’ll explain how to best structure your documentation, and offer some tips and best practices you might consider as you’re tightening up your docs.
Before you start mapping out your docs structure, first talk to other stakeholders and contributors to get their views on the best way to organize your content.
While the ultimate goal is to make it easier for your users to find what they need, it’s just as important that everyone on the team knows how to contribute to your docs, and don’t have to jump through hoops to do it.
You might want to put together a short Contribution Guide, if your docs setup is complex. Or you might want to consider a new documentation platform with useful tools built in. Some, like GitBook, include Git Sync, which lets you sync your docs with GitHub or GitLab — allowing technical people to update docs from their code editor, while offering an intuitive but powerful editor for those that prefer it.
Once you’re happy with your setup and your team are on board, you can think about how best to bring all your content together
The term ‘documentation’ covers a wide array of content — and there’s no reason why you can’t bring all of them into your structure.
To give you an idea, here are a few types of documentation you might already create, or might want to consider as you build your structure
API docs/API reference – If your product uses an API, having API docs or API reference docs helps your users quickly find, explore, test and use it.
Quickstart / Explanation – You may have a quickstart guide at the start of your product docs, or in a standalone section.
Tutorials – Tutorials are learning-oriented. They are practical activities, but the goal is the aquisition of practical knowledge, rather than achieving a specific goal
How-to guides – Guides are goal-oriented. Users will enter the guide with a goal, and the guide should help them achieve that goal.
Changelog/release notes – If you have product documentation, it often makes sense to include a changelog alongside it to show what’s new and point people to the latest docs.
FAQs/help center – If you consider your docs as a support tool, it can be useful to include a help center or FAQ section alongside the rest of your docs.
This is far from an exhaustive list of documentation types. There may be others you want to include in your structure, such as a product blog, a video guides page, or a contributing guide for open source projects.
Of course, there's more than one way to structure documentation. There’s certainly no single right answer that will always work for every product.
However, the two most important factors to consider when deciding on a structure are your product, and your users.
Think about your existing documentation, and any other types you’re considering in the near future. What are the most important to your users, and which will they need the most?
You can build your own structure based on these considerations and conversations with your team. Alternatively, you might want to to turn to an established documentation framework and either use it as-is, or adapt it for your particular use case.
Documentation frameworks are designed to create structure within your docs by assigning a role to each piece of content you create.
There’s a lot of specific details about the framework that we won’t get into here, but you can head over to the Diátaxis site to learn more about it, and analyze how easily you could apply it to your own documentation structure.
It’s worth noting that Diátaxis is a great basis for your documentation structure, but you don’t have to follow it to the letter. After all, no framework is perfect. The dividing lines between the different categories aren’t always clear, and in some situations it leans more into theory than practicality.
What we’re saying is that you may want to follow a framework like this to the letter, or you may want to use it as a starting point for developing your own framework. And both of those are totally legitimate approaches.
Now that we know the theory, let’s put it into practice.
Whatever content groups you create, you now need to think about what most people will want to see first, and what your priories are as a team.
Are you focused on improving your onboard? Make sure docs visitors can easily access your Quickstart guide — or even land there by default. Are most of your support tickets about your API? Make sure it’s clearly labelled and easy to find on your docs site.
When people click through to your docs, what’s the first thing they’ll see? Make sure your landing page clearly explains what the user is looking at, and include links to you most popular pages. You might want to use cards and imagery to add some brand.
Most documentation tools let you add all these things to a single website, with a navigation bar to help users switch between different types of docs. Some even let you add drop-down menus to this navigation bar, to group even more kinds of content together.
Okay, things are shaping up. You’ve got your top-level docs structure and now it’s time to consider how your content fits into each of those sections
Let’s think about some product docs, for example. How do you decide what order to document the features and processes you can follow? How do you group different sets of features together?
This will depend entirely on what you’re documenting but here are some quick tips:
Now that you’ve got a docs structure you’re happy with and a clear idea of precisely where each kind of content belongs, make sure your team are all on the same page. Create workflows for adding or updating content, share them, and make sure they’re easy to access.
That means you can set up a process that includes branching, and review and approval steps that encourage collaboration, guarantee the quality of your docs will be maintained, and avoid conflicts.
We’ve mentioned it a few times already, but GitBook has a number of powerful features that make it easy to structure and maintain the quality of your docs.
The most popular and well-known framework is Diátaxis. It sets out a systematic approach to documentation structure that organizes content into four categories — tutorials, how-to guides, reference and explanation.
Depending on the structure you’ve chosen, you can now start grouping content together. That might be clearly-defined sections for API docs, product docs, guides, and FAQs. Maybe it includes a changelog or a blog.
Create page groups – Group pages together under titles to bring related subjects together, and make it easier for your users to find the information they need at a glance.
Add pages and subpages – When a topic is large or you need to add things like technical guides that relate to it directly, add them as a subpage. This creates hierarchy in your docs, but we’d suggest only creating a maximum two levels of subpages — any more and things can become confusin.
Use H1-H4 headings – Add headings to your page to denote hierarchy within a page’s content. Give each page an H1 heading at the top, then use H2, H3 and H4 headings to break up ideas. Be consistent about how you use them to make it easier to scan a page for information. Some documentation tools use headings to create an ‘On this page’ section that lets you jump between headings fast.
You may also want to consider new workflows for updating your content. If you use GitHub already, you probably already have a review system in place for docs updated. Many documentation platforms, such as GitBook, can sync your docs to a specific Git repository, and use a similar branch-based workflow for docs.
Site sections and site section groups – Add multiple content spaces to a single site and organize them into a tabbed navigation bar with drop-down groups if needed.
Effortless navigation – GitBook automatically creates a table of contents for your docs, with an ‘On this page’ section to make it easy to browse and jump to specific page sections.
Global search – No matter how many kinds of documentation you publish in a single site, you can search across them all and use Ask AI to find information fast.
And there’s more to GitBook — including built-in content insights and interactive OpenAPI blocks that let your users test endpoints right on the page. Try it out for yourself or find out more on our website.
Cross-reference – Linking between related pages is essential. Don’t explain concepts or features on multiple pages — it’s a waste of time, and will become increasingly hard to keep track of and update when things change. Instead, add links to direct people to more information if they need it. Consider adding a link to a word or concept the first time it appears on the page, but also adding in dedicated links to related content wherever relevant.
Use global search – When you have multiple kinds of documentation (such as API docs, product docs, FAQs etc) on a single docs site, enabling global search will help users find what they need without having to click through multiple tabs and pages. Dedicated documentation tools like GitBook support global search natively.
Write for AI – If your docs offer an AI search option — which uses information from your docs to train an assistant that can answer questions — then you should keep that in mind while writing. The best way to do that are being consistent about the way you name or describe specific features or processes, writing in the second person (aka saying ‘you’, not ‘we’ or ‘they’) and adding FAQs to each page with extra detail. H1-H4 headings help, too.
GitHub and GitLab Sync – Sync your content to GitHub or GitLab so your developers can update your docs from Git, while less technical team members work in the built-in editor.
Branch-based workflow – Encourage collaboration and protect your primary docs with intuitive branching, including reviews and conflict resolution.
Beautiful out of the box – Your docs will look incredible in GitBook, even if you just hit publish. But you’ll also get a ton of customization options to build docs that match your brand.