Well-organized documentation helps your users find the answers they need quickly and effortlessly. By structuring your content into logical sections and entries, you create a seamless reading experience that guides users from basic concepts to advanced features.
This guide explains how to organize your documentation hierarchy, manage sections, and keep your content neatly structured.
Understanding the content hierarchy
Before creating your content, it helps to understand how information is organized within the platform. Content is nested in a top-down structure, ensuring everything has a clear, predictable home.
flowchart TD
A["Documentation Project"] --> B["Version (e.g., v1.0)"]
B --> C["Section: Getting Started"]
B --> D["Section: API Reference"]
C --> E["Entry: Installation"]
C --> F["Entry: Quickstart"]
D --> G["Entry: Authenticate"]| Element | Description | Example |
|---|---|---|
| Version | A specific release or iteration of your documentation. | v2.0, latest |
| Section | A category or folder used to group related topics together. | Getting Started, Core Concepts |
| Entry | An individual documentation page, guide, or API endpoint. | Installation Guide, Create User |
Managing sections
Sections act as the primary folders for your documentation. You can create, update, reorder, and delete sections to build the perfect navigation menu for your readers.
Creating a new section
- 1
Select your version
Navigate to the specific documentation project and select the Version you want to edit.
- 2
Add a section
Click the Create Section button in your content manager.
- 3
Name your section
Give your section a clear, descriptive title (e.g., "Authentication" or "Webhooks").
- 4
Populate with entries
Begin adding individual documentation entries into your newly created section.
Keep section titles short and action-oriented. Users scan navigation menus quickly, so titles like "Managing Users" perform better than "Information About How to Manage Users".
Reordering content
As your product grows, your documentation will too. You can easily adjust the flow of your documentation to ensure a logical reading path.
To reorder sections, use the drag-and-drop interface in your content manager to move sections up or down. The order you set here dictates exactly how the navigation menu will appear to your end-users.
Reordering sections automatically updates the navigation structure across your published documentation without requiring a full site rebuild.
Source of truth summaries
If your documentation is synced from external repositories or codebases, the system maintains a source-of-truth summary for each section. This allows you to track exactly where the content originated, ensuring your sections remain accurate and up-to-date with your codebase.
Frequently asked questions
What happens to my entries if I delete a section?
When you delete a section, you will be prompted to either delete the nested entries as well, or move them to a different section. Be careful when deleting sections to avoid accidentally removing important pages!
Can I have empty sections?
Yes, you can create empty sections as placeholders while you draft your content. However, empty sections will not be visible to your end-users in the published documentation until they contain at least one published entry.
Next steps
Once your sections and entries are structured perfectly, you're ready to share them with the world or manage access for your team.