Master this essential documentation concept
An organizational structure in documentation platforms where content is arranged in nested parent-child relationships, creating a tree-like information hierarchy.
Hierarchical Spaces provide documentation teams with a structured framework for organizing content across multiple levels of depth and specificity. Rather than storing documents in flat, unrelated collections, this approach creates meaningful relationships between content units, making large documentation repositories manageable and intuitive for both creators and end users.
A software company with five distinct products has documentation scattered across shared drives, wikis, and individual team folders. Users cannot find product-specific information, and writers accidentally overwrite each other's work due to lack of clear ownership.
Implement a Hierarchical Spaces structure with a root organizational space containing individual product spaces, each subdivided by documentation type such as user guides, API references, and release notes.
1. Create a root space called 'Documentation Hub' as the master container 2. Create five child spaces, one per product (e.g., 'Product A Docs', 'Product B Docs') 3. Within each product space, create sub-spaces for 'Getting Started', 'User Guides', 'API Reference', and 'Release Notes' 4. Assign product team ownership at the product-level space 5. Configure permission inheritance so product managers control their branch 6. Migrate existing content into the appropriate sub-spaces 7. Create a root-level index article linking to all product spaces
Writers have clear ownership boundaries, users can navigate directly to their product's documentation, and new product launches simply require adding a new branch to the existing hierarchy without disrupting current content.
HR and department managers struggle to onboard new employees efficiently because onboarding materials are split between role-specific guides, company policies, and tool documentation with no logical connection between them.
Build a hierarchical onboarding space where the top level separates content by audience (All Employees, Department-Specific, Role-Specific), with each branch containing progressively more specialized content.
1. Create a parent 'Onboarding Hub' space 2. Add three primary child spaces: 'Company-Wide Essentials', 'Department Spaces', and 'Role Playbooks' 3. Under 'Department Spaces', create sub-spaces for Engineering, Marketing, Sales, and Support 4. Within each department space, create 'Week 1', 'Week 2-4', and 'Ongoing Resources' sub-spaces 5. Link role-specific playbooks to relevant department spaces using cross-space references 6. Set read permissions so new hires see only their relevant branch until cleared for broader access 7. Create a single 'Start Here' article at the root space that routes users to their specific path
New employees follow a clear, personalized documentation path, managers spend less time directing people to resources, and HR can update company-wide policies in one place with changes reflected across all department branches.
A developer tools company maintains API documentation for three active versions simultaneously. Documentation writers frequently update the wrong version, and developers cannot reliably find documentation for their specific version without extensive searching.
Create a version-based hierarchical structure where each API version lives in its own space branch, with shared reference materials in a parent space accessible to all version branches.
1. Create a root 'API Documentation' parent space 2. Add a 'Shared Resources' child space for authentication guides, glossary, and error codes that apply to all versions 3. Create version-specific child spaces: 'API v1 (Legacy)', 'API v2 (Stable)', 'API v3 (Current)' 4. Within each version space, mirror the same sub-space structure: 'Endpoints', 'Tutorials', 'Changelog', 'Migration Guide' 5. Use space-level banners to clearly label version status (deprecated, stable, beta) 6. Configure the v3 space as the default landing point for new visitors 7. Add cross-space links in each version's migration guide pointing to the next version's space
Developers land on the correct version immediately, writers work in isolated version branches preventing accidental cross-version edits, and deprecating old versions requires only archiving a single space branch.
A global company needs to maintain documentation in English, Spanish, French, and Japanese. Currently, translated documents are mixed with source documents, causing translators to work on outdated versions and users to accidentally read content in the wrong language.
Implement a language-based hierarchical structure where each language has its own top-level space mirroring the same sub-space structure as the source language, with a shared 'Source Content' space that translators reference.
1. Create a 'Global Documentation' root space 2. Establish 'EN (Source)' as the master content space with the full sub-space hierarchy 3. Create parallel child spaces for 'ES', 'FR', and 'JA', each with identical sub-space structures 4. Set the EN space as read-only for non-English writers to prevent accidental edits 5. Configure language-specific spaces with permissions for respective localization teams 6. Add a 'Translation Status' article in each language space tracking which articles are current 7. Create a language selector at the root space level that routes users to their preferred language branch 8. Set up notifications so localization teams are alerted when source EN content is updated
Translators always work from clearly identified source content, users are routed to their language automatically, and documentation managers can audit translation completeness by comparing space structures across language branches.
Before creating any spaces, research how your users actually think about and categorize your content. Conduct card sorting exercises or analyze search queries to understand the natural groupings users expect. A hierarchy that reflects writer logic rather than user expectations creates friction and increases support requests.
Every additional level of nesting adds cognitive overhead for both writers and readers. Users navigating deep hierarchies lose context and struggle to understand where they are relative to the broader documentation structure. Writers working in deeply nested spaces often struggle to decide where new content belongs, leading to inconsistent placement.
Inconsistent space naming creates confusion when users browse the hierarchy and when writers decide where to place new content. Names that are too generic (like 'Resources' or 'Other') become catch-all spaces that undermine the entire organizational system. Establishing naming conventions upfront prevents costly restructuring later.
Hierarchical Spaces become significantly more powerful when permission structures are designed alongside the content structure. Parent space permissions that cascade to children reduce administrative overhead and ensure consistent access control. However, poorly planned inheritance can either over-expose sensitive content or create unnecessary access barriers for legitimate users.
Once users and writers are accustomed to a hierarchical structure, reorganizing it causes broken bookmarks, confused navigation, and lost content. Without a governance process, individual writers may create redundant spaces, rename existing ones, or move content without coordinating with the broader team. Structural changes need oversight to protect the documentation investment.
Join thousands of teams creating outstanding documentation
Book a Demo