Documentation Information Architecture Template (Diátaxis, llms.txt)

Documentation Information Architecture: [Product or docs site name]

Specification of how a documentation site is organised: who it serves, which content types exist and where each lives, the top-level navigation, the site-map tree, the URL and slug scheme, how docs are versioned, the landing-page pattern, cross-link rules, search facets, the redirect policy, and the agent-readable outputs (llms.txt and Markdown mirrors). The content-type map follows the Diátaxis framework (diataxis.fr, CC BY-SA 4.0), agent outputs follow the llms.txt proposal (llmstxt.org, last modified 2026-08-10), and the navigation and structure topics are aligned with ISO/IEC/IEEE 26514:2022. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. Scope and audiences
2. Content-type map
3. Top-level navigation
4. Site-map tree
5. URL and slug scheme
6. Docs versioning
7. Landing-page pattern
8. Cross-link rules
9. Search and facets
10. Redirect policy
11. Agent-readable outputs
12. Governance and validation
13. Glossary and references
14. Standard and licence note

1. Scope and audiences

State the boundary of the site in one paragraph: which products and versions it covers, which content lives elsewhere (marketing site, support knowledge base, community forum, internal wiki), and which languages are published. Then list the audiences and the entry points each one uses, because the entry point decides which page must work as a first page.

Out of scope for this specification: page-level writing rules (see Technical Style Guide (docs/style-guide-technical)), the production schedule and staffing (see Documentation Plan (docs/documentation-plan)) and the review gate for each page (see Docs Review Checklist (docs/docs-review-checklist)).

2. Content-type map

Diátaxis separates documentation by two questions: does the reader need to act or to understand, and are they acquiring a skill or applying one at work. The answers give four types: tutorials (act, acquire), how-to guides (act, apply), reference (understand, apply) and explanation (understand, acquire). Use these four as the top classifier for every page, then allow a small set of page types under each.

2.1 Allowed page types

Rules for page types:

• Give each page exactly one page type and record it in front matter (for example type: how-to). The build fails when the field is missing or not in this table.
• Do not mix types on one page. When a how-to guide needs background, link to the explanation page instead of embedding it.
• Add a new page type only through a change to this document, so that templates, search facets and analytics stay aligned.

2.2 Coverage per product area

Mark each cell with the number of pages planned or published and flag gaps. An empty cell is a decision, not an accident: write "None by design" with the reason.

3. Top-level navigation

Choose one primary organising principle for the top level and use the other as a secondary level. For most multi-product sites, product area first and Diátaxis type second works best, because readers arrive knowing the product but not the documentation theory. Single-product sites can put the four types at the top.

Navigation rules:

• Keep the top level at seven items or fewer and the visible depth at three levels. Deeper content is reached through landing pages.
• Use labels a new reader understands. Product names are allowed; internal code names, team names and abbreviations are not.
• Order sidebar items by task sequence inside a tutorial or how-to set, and alphabetically inside reference sets.
• Show the reader where they are with breadcrumbs on every page below the top level.

4. Site-map tree

Keep the tree as plain text in this document and as a machine-readable file in the repository (for example nav.yml). Each node shows the path segment and, for leaves, the page type ID.

/                                   landing (PT-10)
├── get-started/                    landing (PT-10)
│   ├── create-account              PT-03
│   ├── checkout-quickstart         PT-01
│   └── orders-quickstart           PT-01
├── checkout/                       landing (PT-10)
│   ├── tutorials/
│   │   ├── build-a-hosted-checkout PT-02
│   │   └── accept-saved-cards      PT-02
│   ├── guides/
│   │   ├── handle-webhooks         PT-03
│   │   ├── issue-refunds           PT-03
│   │   └── test-in-sandbox         PT-03
│   ├── concepts/
│   │   ├── payment-lifecycle       PT-07
│   │   └── idempotency             PT-07
│   └── api/                        PT-05 (generated)
├── orders/                         landing (PT-10)
│   ├── guides/
│   ├── concepts/
│   └── api/                        PT-05 (generated)
├── data/                           landing (PT-10)
│   ├── orders-data-product/
│   └── checkout-data-product/
├── reference/
│   ├── errors                      PT-06
│   ├── rate-limits                 PT-06
│   └── webhook-events              PT-06
├── changes/
│   ├── release-notes               PT-08
│   ├── api-changelog               PT-08
│   ├── deprecations                PT-08
│   └── known-issues                PT-09
└── help/
    ├── troubleshooting             PT-04
    └── faq                         PT-10 (routing page only; links into troubleshooting and how-to)

The Mermaid view below is for reviews; the text tree stays canonical.

5. URL and slug scheme

Define URLs as a grammar and give one example per pattern.

Set one canonical URL per page with <link rel="canonical">, and point every language and version variant at the correct canonical (section 6).

6. Docs versioning

Pick one model and state why.

Versioning rules for the chosen model:

• Supported versions shown: [List, for example "current and previous major"]. Older versions move to an archive path with a visible "unsupported version" banner. Use either canonical-to-current or noindex for archived versions, not both.
• Default: unversioned URLs always serve the current version.
• Canonical: each versioned page sets its canonical to the current version's equivalent page when the content is equivalent, and to itself when it differs materially.
• Version switcher: keeps the reader on the same page in the target version when it exists; falls back to that version's landing page, never to a 404.
• End of support: when a version leaves support, publish a notice using Deprecation Notice (docs/deprecation-notice) and keep the archive for [period].

Example: Corvid Commerce documents the Checkout API as one unversioned site and shows dated API versions inside reference pages, while its self-hosted connector has /connector/v3/ and /connector/v4/ with v3 marked unsupported from YYYY-MM-DD.

7. Landing-page pattern

Every top-level area and every section folder has a landing page built from the same blocks, in this order:

1. Title and one-sentence purpose: what this area lets the reader do.
2. Start here: one primary call to action, normally the quickstart or the most common task.
3. Paths by Diátaxis type: four short groups (learn, do, look up, understand), each with three to six links. Omit a group only when section 2.2 says "None by design".
4. Popular tasks: the five most used how-to guides, refreshed from aggregate page-view data each quarter.
5. Changes and status: link to the area's release notes, known issues and active deprecations.
6. Get help: troubleshooting, community and support routes.

Keep landing pages short enough to scan without scrolling on a laptop screen. Do not put procedures on landing pages; they become hard to find and impossible to version cleanly.

8. Cross-link rules

9. Search and facets

Every page carries front-matter metadata that feeds search, analytics and validation. Facets are built only from fields the build enforces.

Search behaviour rules:

• Boost reference entries for exact identifier matches (error codes, endpoint names, setting keys).
• Exclude archived versions from default results; include them only when the reader selects that version.
• Keep a synonyms list sourced from the termbase so that "refund" also finds "reversal" where the product uses both terms.
• Review zero-result queries monthly from aggregate, anonymous search logs. Do not store queries with user identifiers; honour Global Privacy Control and the site consent settings for any measurement.

10. Redirect policy

11. Agent-readable outputs

The llms.txt proposal (llmstxt.org, first published 2024-09-03, last modified 2026-08-10) defines a Markdown index file and a convention for Markdown versions of pages. Use the llms.txt (dev/llms-txt) template for the file itself; this section fixes where it lives and how it maps to the site map.

Example: Corvid Commerce publishes /llms.txt with sections Get started, Checkout API, Orders API, Data products, Reference and Optional. Each page such as /checkout/guides/issue-refunds has a mirror at /checkout/guides/issue-refunds.md, and the CDN adds a Link header with rel="alternate" and rel="describedby".

12. Governance and validation

12.1 Validation before launch

Use fictional or recruited participants with consent, and keep results aggregate. Do not record personal data that the test does not need.

12.2 Build-enforced rules

• Front matter has type, area and last_verified with valid values.
• Every page appears exactly once in nav.yml, and every entry in nav.yml has a page.
• Every removed path appears in redirects.csv.
• Markdown mirrors exist for every published page and llms.txt links resolve.

12.3 Change control

13. Glossary and references

13.1 Glossary

13.2 References

Standard and licence note

Structure aligned with ISO/IEC/IEEE 26514:2022 for the topics of structure and navigation of information for users; no ISO text, table or definition is reproduced. The content-type map is adapted from the Diátaxis framework by Daniele Procida (https://diataxis.fr/), licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0); if you redistribute material adapted from Diátaxis, credit Diátaxis and license that adapted material under CC BY-SA 4.0 or a compatible licence. The agent-readable outputs section is based on the public llms.txt proposal at llmstxt.org, which states no licence and is cited only. All wording in this template is original text written for this collection. Check the current official versions of these sources before use. Template licence: MIT.