Documentation structure shapes how quickly developers find what they need. Whether you're maintaining a single API reference or managing docs across a portfolio of products, the underlying information architecture determines whether developers spend their time building or searching.
The challenge scales with complexity. A single-product API needs minimal structural overhead — clear sidebar groups and version selectors. Multi-product platforms require boundaries between services so developers don't confuse which endpoints or auth methods apply. And enterprise systems with nested product hierarchies need navigation that scales without burying content behind five layers of menus.
Fern's documentation platform is built around these patterns. This guide covers IA best practices for developer documentation and shows how Fern implements them — from content type frameworks and architecture tiers to navigation elements and product switchers in docs.yml.
TLDR:
- Frameworks like Diátaxis, task-based IA, and topic-based authoring provide the foundation for organizing documentation by user intent rather than internal product structure.
- Documentation architecture falls into three tiers: single-context sites, multi-context portfolios, and deep-context platforms — each with different navigation requirements.
- Progressive disclosure through accordions, tabs, and collapsible sidebars reduces cognitive load by revealing content only when needed.
- Fern's
docs.ymlconfiguration handles product switchers, version selectors, navigation tabs, and shared content snippets across nested product hierarchies.
Information architecture frameworks for technical documentation
The best documentation is organized around what developers need to do, not how your product is built internally. Three frameworks help structure that thinking.
The Diátaxis framework divides content into four quadrants: tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), and explanation (understanding-oriented). Each quadrant serves different developer needs at different stages. This matters when you're deciding where a new page goes — if it's teaching a concept, it belongs in explanation, not crammed into an API reference.
Task-based information architecture takes this further by organizing content around developer goals. Instead of structuring docs by features like "Authentication Module" or "Payment Processing Component," task-based structures group content around actions like "Accept your first payment" or "Set up OAuth authentication."
Topic-based authoring treats each page as a discrete, reusable unit with clear boundaries. A tutorial, API reference, or conceptual explanation each exists independently and links to related topics rather than depending on reading order. This makes it possible to reuse content across products, version individual pages without republishing entire doc sets, and reorganize navigation without rewriting anything.
These frameworks work together. Diátaxis provides the content type taxonomy, task-based organization determines navigation structure, and topic-based authoring enables reuse across product boundaries. Fern's folder-based configuration and Markdown authoring support this naturally — each page is a standalone unit that can be reorganized or shared across products without duplicating source files.
Three architecture tiers for documentation
Documentation architecture falls into three tiers based on product complexity. The tiers map to how developers think about product boundaries: single products need version navigation, product portfolios need context switching, and platform ecosystems need hierarchical drill-down. Selecting the right tier prevents forcing single-product patterns onto multi-product platforms or over-engineering simple docs with unnecessary complexity.
The single-context site architecture
Single-context architecture serves one product with multiple versions. All content lives within a unified information space, and version selectors let developers switch between releases without changing products.
The architecture works through flat visibility. Every page, guide, and API reference exists within the same navigational hierarchy. Since you don't need a product switcher, your primary sidebar groups should explicitly separate content types — tutorials, guides, reference, and explanation. Show the complete map. Don't force developers to click three times to find the API reference.
Version selectors handle temporal changes (v1.0 vs v2.0) while keeping the product context constant. Fern's versioning supports folder-based strategies, availability labels like beta or deprecated, and automatic routing so links resolve correctly when developers switch between releases.
The multi-context portfolio structure
Multi-context structure suits organizations managing several distinct products under one brand. This setup needs product switchers to move between different tools and version selectors to navigate releases within each tool.
When a developer lands in Product A, the sidebar cannot show links to Product B. Developers need to feel they've entered a distinct room with boundaries matching the product's scope. Mixing contexts creates confusion about which API endpoints, authentication methods, or error codes apply to their current task.
Each product gets its own getting started guide, authentication documentation, and API reference without sharing sidebar space with other products. The Diátaxis quadrants reset for each product context — Product A's tutorials are separate from Product B's.
Shared concepts like rate limiting or error handling need a deliberate architectural decision: either duplicate them across product documentation spaces, or house them in a separate platform-level section with its own switcher entry. The hub-and-spoke model — where a central landing page connects to self-contained product docs — gives each product its own complete navigation structure.
Fern supports multi-product docs through product-specific configuration files, each with its own navigation, tabs, and API references. Products can be internal or link to external URLs, and each can be independently versioned or unversioned. Audience-based filtering lets you control which products and versions appear for different user groups — so internal developers and public customers can see different documentation from the same site.
The deep-context platform
Deep-context platforms contain products with their own sub-products. A payments product might include card processing, ACH transfers, and cryptocurrency settlement as distinct tools, each with separate API surfaces, authentication requirements, and version histories.
In nested systems, global sidebars fail because they become too long. Every sub-product needs to act as a sovereign entity with its own navigation context, version selector, and API reference. A developer exploring card processing shouldn't see ACH-specific endpoints unless they navigate there intentionally.
The cross-product challenge is shared content. Authentication, error handling, and rate limits often apply across all nested products, but duplicating source text creates maintenance problems when those flows change. Fern handles this with reusable Markdown snippets that can be referenced across product boundaries — write it once, and it updates everywhere. Fern also builds navigation recursively from nested folder structures, creating collapsible menus that scale with your product hierarchy.
One hard rule: never put a massive enterprise hierarchy into a single expanding sidebar. Developers expect search and drill-down navigation, not scrolling through thousands of lines of tree-view. Progressive disclosure reveals information incrementally, preventing developers from facing the entire documentation hierarchy at once.
Migration paths: when to graduate between architecture tiers
Documentation architecture should match product complexity, but knowing when to migrate between tiers prevents technical debt from accumulating. Teams often start with single-context architecture and face friction as products expand beyond their original structure.
Moving from single-context to multi-context becomes necessary when a second product launches with different authentication, endpoints, or use cases. The signal: developers confuse features between products, or support tickets reveal users reading the wrong product's documentation. At this point, product switchers replace or supplement version selectors.
Graduating from multi-context to deep-context happens when a product develops sub-products with distinct API surfaces. A payments API that adds fraud detection, then dispute management, then settlement optimization needs hierarchical navigation. The trigger: each sub-feature requires its own getting started guide, authentication flow, or version history independent of the parent product.
URL structure determines migration complexity. Flat patterns like /docs/v2/endpoint force breaking changes when adding products. Hierarchical patterns like /docs/product/v2/endpoint accommodate growth without URL rewrites. Fern's folder-based configuration maps directly to URL patterns, so migration is a matter of reorganizing directories and configuration files rather than rewriting routing logic. Fern also handles redirects automatically when URLs change, preserving SEO rankings and existing bookmarks.
The cost of delaying migration increases with documentation volume. Migrating 50 pages takes days. Migrating 500 pages with established SEO rankings, external links, and bookmarked URLs takes weeks and risks breaking developer workflows.
Navigation elements: when to use each
Each navigation element serves a specific purpose in documentation architecture. Using the wrong one — like tabs where you need a product switcher — creates confusion about where developers are in your docs.
Fern supports all of these elements through docs.yml configuration. Version selectors and product switchers are generated automatically from your versions and products definitions. Tabs are defined under the tabs key in each product's configuration and can link to internal sections or external docs. Collapsible sidebar navigation is built recursively from nested folder structures, and accordions are available as Markdown components within any page.
How Fern simplifies information architecture
Most of the patterns above require custom engineering — building product switchers, managing version routing, handling shared content across products. Fern handles this through configuration.
Instead of writing custom routing logic or building navigation components, teams define their documentation architecture in docs.yml files and folder structures. Fern generates the URL patterns, switcher placement, and navigation trees from these configurations. Reorganizing product hierarchies, adding versions, or introducing sub-products is a matter of editing config files, not rewriting infrastructure.
This configuration-based approach means documentation architecture decisions stay reversible. The migration paths described earlier — single-context to multi-context to deep-context — become directory reorganizations rather than engineering projects. Teams can start simple and add complexity as their product portfolio grows, without rebuilding their docs platform at each tier.
Fern also generates type-safe SDKs and interactive API references, keeping documentation consistent across products. When an API spec changes, the generated references and SDKs update together, preventing drift between what the docs say and what the SDK does. Companies like Square and Webflow use Fern to manage documentation across complex product portfolios.
Final thoughts on structuring docs for optimal navigation
Information architecture decisions compound. The URL patterns, navigation hierarchy, and switcher placement you choose early determine how painful future migrations become. Start with the simplest tier that fits your current product complexity, but use hierarchical URL structures and modular content so you can scale without breaking what already works.
Book a demo to see how Fern handles documentation architecture for multi-product platforms.
FAQ
How should I structure documentation for multiple products under one brand?
Use a multi-context portfolio structure where each product gets its own navigation, getting started guide, and API reference. Product switchers in the header or sidebar let developers move between tools without mixing contexts. Fern supports this through product-specific configuration files with independent navigation and versioning.
When should I use a product switcher versus a version selector?
Product switchers handle spatial navigation between distinct products — like moving from a payments API to a fraud detection tool. Version selectors handle temporal navigation within a single product — like switching from v1.0 to v2.0. If the content shares the same API surface, use versions. If the APIs are fundamentally different, use products.
What's the difference between single-context and multi-context documentation architecture?
Single-context serves one product with multiple versions using version selectors. Multi-context manages several distinct products under one brand, requiring both product switchers and version selectors. The key difference is whether developers need to switch between fundamentally different tool contexts.
How can I reduce cognitive load in nested documentation?
Limit visible navigation to three to five top-level products, use progressive disclosure to reveal deeper layers only when needed, and keep switcher placement consistent so developers learn the interface patterns once.
How does Fern handle shared content across multiple product docs?
Fern uses reusable Markdown snippets that can be referenced across product documentation spaces. Authentication guides, error dictionaries, and rate limiting explanations exist in one place and update everywhere they're referenced.
