# 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*.

<!--
Guidance: How to use this template
- Write this specification before a docs site is built, before a
  re-platforming, or when the navigation has grown by accretion and
  readers report that they cannot find pages.
- Fill sections 1 and 2 first: audiences and the content-type map
  drive every other decision. A navigation designed before the
  content types are agreed tends to mirror the org chart.
- Keep the site-map tree (section 4) as the single source of truth
  for page placement. The docs build should be able to check the
  real navigation against it.
- Treat URLs as a public interface. Every rule in sections 5, 6 and
  10 exists to stop links in tickets, forums, code comments and
  agent indexes from breaking.
- Related documents: Documentation Plan (`docs/documentation-plan`),
  Technical Style Guide (`docs/style-guide-technical`), Content Audit
  (`docs/content-audit`), Docs Review Checklist
  (`docs/docs-review-checklist`), llms.txt (`dev/llms-txt`), Glossary
  (`docs/glossary`), Deprecation Notice (`docs/deprecation-notice`).
- The worked example is a fictional company, Corvid Commerce, that
  publishes docs for its Checkout API, Orders API and data products.
-->

## Document control

<!-- Guidance: Identify the docs site, the platform it is built on and who owns the information architecture. Changes to top-level navigation or the URL scheme are a new minor version. -->

| Field | Value |
|---|---|
| Document ID | [IA-001] |
| Docs site | [Product name] documentation at [https://docs.example.com] |
| Docs platform and generator | [Static site generator, version] |
| Source repository | [org/docs-repo] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@docs-lead] |
| Approvers/reviewers | [@product-lead], [@developer-relations-lead], [@seo-or-web-lead], [@support-lead] |
| Last updated | YYYY-MM-DD |
| Classification | [Internal / Public] |
| Related documents | [Documentation plan], [Style guide], [Content audit], [llms.txt] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Documentation lead | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Product lead | [@name] | [Decision] | YYYY-MM-DD |
| Web or platform owner | [@name] | [Decision] | YYYY-MM-DD |
| Support lead | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved after tree test round 2 |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added the Data products top-level section and its redirects |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Scope and audiences](#1-scope-and-audiences)
2. [Content-type map](#2-content-type-map)
3. [Top-level navigation](#3-top-level-navigation)
4. [Site-map tree](#4-site-map-tree)
5. [URL and slug scheme](#5-url-and-slug-scheme)
6. [Docs versioning](#6-docs-versioning)
7. [Landing-page pattern](#7-landing-page-pattern)
8. [Cross-link rules](#8-cross-link-rules)
9. [Search and facets](#9-search-and-facets)
10. [Redirect policy](#10-redirect-policy)
11. [Agent-readable outputs](#11-agent-readable-outputs)
12. [Governance and validation](#12-governance-and-validation)
13. [Glossary and references](#13-glossary-and-references)
14. [Standard and licence note](#standard-and-licence-note)

## 1. Scope and audiences

<!-- Guidance: Say which content is in scope and who reads it. Questions: which products, which audiences, which entry points (search engine, in-product help, support links, agents)? Pitfall: writing one navigation for "developers" when operators, integrators and evaluators need different starting points. -->

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.

| Audience ID | Audience | Primary goal | Main entry points | Must reach in two clicks |
|---|---|---|---|---|
| AUD-001 *(Example)* | Integrating developer at a merchant | Take a first payment with the Checkout API | Search engine, quickstart link in the dashboard | Quickstart, API reference, error codes |
| AUD-002 *(Example)* | Platform operator | Configure webhooks, keys and limits | In-product help links, support replies | Configuration reference, how-to guides, known issues |
| AUD-003 *(Example)* | Data consumer | Understand the Orders data product and its contract | Data catalogue links | Data product overview, schema reference, change log |
| AUD-004 *(Example)* | Evaluator or architect | Judge fit and limits before buying | Search engine, sales follow-up | Concepts, architecture explanation, limits |
| AUD-005 *(Example)* | Coding agent or assistant | Retrieve current, correct pages as context | `llms.txt`, Markdown mirrors | Same pages as AUD-001 in Markdown |

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

<!-- Guidance: Map each product area to the four Diátaxis types and name the page types you allow. Questions: does every area have at least one tutorial or quickstart, a how-to set, reference and explanation? Pitfall: a single "Guides" bucket that mixes learning, task and reference content, which Diátaxis exists to prevent. -->

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

| Page type ID | Page type | Diátaxis type | Template | Purpose |
|---|---|---|---|---|
| PT-01 | Quickstart | Tutorial | Quickstart (`docs/quickstart`) | First success in under fifteen minutes |
| PT-02 | Tutorial | Tutorial | Tutorial (`writing/tutorial`) | Guided lesson with a known end state |
| PT-03 | How-to guide | How-to | How-to Guide (`docs/how-to`) | One real task for a competent user |
| PT-04 | Troubleshooting | How-to | Troubleshooting (`docs/troubleshooting`) | Symptom to resolution |
| PT-05 | API reference | Reference | API Reference (`dev/api-reference`) | Generated from the API description |
| PT-06 | Configuration or CLI reference | Reference | Configuration Reference (`docs/configuration-reference`), CLI Reference (`docs/cli-reference`) | Complete, consistent lookup |
| PT-07 | Concept or explanation | Explanation | Explanation (`docs/explanation`) | Why and how it works, trade-offs |
| PT-08 | Release notes and changelog | Reference | Release Notes (`dev/release-notes`), API Changelog (`docs/api-changelog`) | What changed, by version |
| PT-09 | Known issues register | Reference | Known Issues (`docs/known-issues`) | Current defects and workarounds |
| PT-10 | Landing page | Navigation | Section 7 of this document | Route readers into an area |

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.

| Product area | Tutorials | How-to guides | Reference | Explanation | Gaps and decisions |
|---|---|---|---|---|---|
| Checkout API *(Example)* | 1 quickstart, 2 tutorials | 14 | API reference, error codes, webhooks events | 4 | No tutorial for refunds yet: planned Q[n] |
| Orders API *(Example)* | 1 quickstart | 9 | API reference, status model | 2 | Explanation of order states missing |
| Orders data product *(Example)* | None by design: consumers use the catalogue | 3 | Schema, contract, service levels | 1 | Contract changes link to the data change log |
| Dashboard and accounts *(Example)* | 1 | 11 | Settings reference | 1 | None |
| [Product area] | [n] | [n] | [Pages] | [n] | [Gaps] |

## 3. Top-level navigation

<!-- Guidance: Define the first level a reader sees. Questions: is the top level organised by product area, by Diátaxis type, or by audience, and why? Pitfall: more than seven top-level items, or labels that use internal product code names. -->

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.

| Order | Label | Path | Contains | Rationale |
|---|---|---|---|---|
| 1 *(Example)* | Get started | `/get-started/` | Account setup, quickstarts for each API | Shortest path to first success for AUD-001 |
| 2 *(Example)* | Checkout API | `/checkout/` | Guides, reference, concepts for Checkout | Largest area by traffic |
| 3 *(Example)* | Orders API | `/orders/` | Guides, reference, concepts for Orders | Separate lifecycle and owners |
| 4 *(Example)* | Data products | `/data/` | Orders and Checkout data products | Different audience (AUD-003) |
| 5 *(Example)* | Reference | `/reference/` | Cross-product reference: errors, limits, events | Lookups that span products |
| 6 *(Example)* | Changes | `/changes/` | Release notes, API changelog, deprecations, known issues | One place to watch for change |
| 7 *(Example)* | Help | `/help/` | Troubleshooting, FAQ, support contact | Entry from support links |

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

<!-- Guidance: Draw the canonical tree that the build can check against. Questions: does every page have exactly one parent, and does every leaf belong to a page type from section 2.1? Pitfall: the same page linked from two places in the navigation, which splits analytics and confuses breadcrumbs. -->

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.

```text
/                                   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.

```mermaid
flowchart TD
  Home[Docs home] --> GS[Get started]
  Home --> CO[Checkout API]
  Home --> OR[Orders API]
  Home --> DP[Data products]
  Home --> RF[Reference]
  Home --> CH[Changes]
  Home --> HP[Help]
  CO --> COT[Tutorials]
  CO --> COG[How-to guides]
  CO --> COC[Concepts]
  CO --> COA[API reference]
  CH --> KI[Known issues]
  HP --> TS[Troubleshooting]
  TS -. links .-> KI
```

## 5. URL and slug scheme

<!-- Guidance: Fix the URL grammar before the first page ships. Questions: do URLs carry the version and language, and in which order? Are slugs derived from titles or set by hand? Pitfall: putting the Diátaxis type or a team name in the URL, which forces redirects every time content is reclassified. -->

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

| Rule ID | Rule | Example |
|---|---|---|
| URL-01 | Pattern: `/{lang}/{version}/{area}/{section}/{slug}`; omit `{lang}` for the default language and `{version}` for the current version | `/checkout/guides/issue-refunds` *(Example)* |
| URL-02 | Slugs are lowercase ASCII words joined by hyphens, no dates, no file extensions in the canonical URL | `handle-webhooks`, not `Handle_Webhooks_v2.html` |
| URL-03 | Slugs describe the task or subject, not the page type label | `issue-refunds`, not `how-to-refunds` |
| URL-04 | Slugs are set by hand in front matter and do not change when the title changes | Title "Refund a payment" keeps slug `issue-refunds` |
| URL-05 | Section folders (`tutorials`, `guides`, `concepts`, `api`) are stable; reclassifying a page between them requires a redirect (section 10) | Moving a page from `guides` to `concepts` adds a 301 |
| URL-06 | Generated API reference lives under one stable prefix per API and uses operation IDs as slugs | `/checkout/api/create-payment` |
| URL-07 | Anchors (heading IDs) on reference pages are stable and explicitly set for any heading that other pages link to | `#error-card_declined` |
| URL-08 | Trailing slash policy: [always / never]; the other form redirects | `/checkout/` canonical, `/checkout` 301 |

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

<!-- Guidance: Decide how many product versions you document and how readers switch. Questions: does the product have versions readers run in parallel (SDKs, self-hosted releases, dated API versions) or is it continuously delivered? Pitfall: copying the whole site per minor release, which multiplies maintenance and search duplicates. -->

Pick one model and state why.

| Model | When it fits | Cost |
|---|---|---|
| Unversioned (latest only) | Continuously delivered SaaS with a single API version | Lowest; changes are announced in release notes |
| Versioned by major release | Self-hosted products or SDKs with parallel supported majors | One docs branch per supported major |
| Dated API versions with one site | APIs that pin behaviour to a version date | Version notes inside reference pages and a version switcher only for reference |

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

<!-- Guidance: Every folder in the tree gets a landing page with the same anatomy. Questions: what is the one first action on each landing page? Pitfall: landing pages that are only an auto-generated list of child pages with no guidance. -->

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

<!-- Guidance: Decide when and how pages link to each other. Questions: which links are mandatory between types, and how are broken links caught? Pitfall: "see also" lists that grow forever and stop being read. -->

| Rule ID | Rule |
|---|---|
| XL-01 | A tutorial ends with links to the next tutorial and to two or three how-to guides that apply what was learned. |
| XL-02 | A how-to guide links to the reference entries for every parameter, setting or command it uses, on first use. |
| XL-03 | A how-to guide links to the explanation page instead of explaining background inline. |
| XL-04 | A reference entry links to at least one how-to guide that uses it, where one exists. |
| XL-05 | Troubleshooting pages link to the matching known-issue ID when a symptom is caused by a known defect. |
| XL-06 | Release notes link to known issues, deprecations and migration guides by ID or anchor, not by vague text. |
| XL-07 | Link text names the destination ("Configure webhook retries"), never "click here" or a bare URL. |
| XL-08 | Internal links are written as source-relative paths and the generator rewrites them per version build, so they resolve within the reader's current version. Never hard-code a version segment. |
| XL-09 | The build runs a link checker on every pull request; broken internal links fail the build, external link failures raise a warning and a weekly report. |
| XL-10 | "Related" lists hold at most five links and are reviewed in the content audit. |

## 9. Search and facets

<!-- Guidance: Define what search indexes and how results can be narrowed. Questions: which metadata fields does every page carry, and which become filters? Pitfall: facets that depend on metadata nobody maintains, so filters silently return incomplete results. -->

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

| Field | Required | Values | Used as facet | Notes |
|---|---|---|---|---|
| `type` | Yes | Page types from section 2.1 | Yes, labelled with Diátaxis names | Lets readers filter to tutorials or reference |
| `area` | Yes | Top-level areas from section 3 | Yes | Default filter is the area the reader is in |
| `version` | When versioned | Supported versions | Yes | Defaults to the reader's selected version |
| `audience` | Optional | AUD IDs from section 1 | No, used for analytics only | Avoid exposing internal audience names |
| `tags` | Optional | Controlled list in the termbase | Yes, top 20 only | Free-text tags are rejected by the build |
| `last_verified` | Yes | YYYY-MM-DD | No | Shown on the page; feeds the content audit |

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

<!-- Guidance: State how URL changes are handled so links never break. Questions: who approves a move, how long redirects live, and how chains are prevented? Pitfall: deleting a page without a redirect because "nobody uses it", which breaks links in support tickets and agent indexes. -->

| Rule ID | Rule |
|---|---|
| RD-01 | Every moved, renamed or merged page gets a permanent (301 or 308) redirect to the closest equivalent page in the same pull request. |
| RD-02 | Deleted pages with no equivalent return 410 Gone (or 404) with links to the parent landing page, unless a close substitute exists. Never redirect them to an unrelated page, which search engines treat as a soft 404. List them in the change log of the docs site. |
| RD-03 | Redirects are kept for at least [period, for example "the lifetime of the domain"]. Removal needs the docs lead's approval and evidence of no traffic. |
| RD-04 | No redirect chains: when a target moves again, update earlier redirects to point straight to the new URL. |
| RD-05 | Redirects are stored as data in the repository (for example `redirects.csv`) and tested in the build. |
| RD-06 | Markdown mirrors (section 11) follow the same redirects as their HTML pages. |
| RD-07 | Temporary (302 or 307) redirects are used only for planned maintenance and expire on a stated date. |

| Redirect ID | From | To | Type | Reason | Date | Approved by |
|---|---|---|---|---|---|---|
| RDR-001 *(Example)* | `/checkout/guides/refunds` | `/checkout/guides/issue-refunds` | 301 | Slug clarified | YYYY-MM-DD | [@docs-lead] |
| RDR-002 *(Example)* | `/guides/webhooks` | `/checkout/guides/handle-webhooks` | 301 | Moved under product area | YYYY-MM-DD | [@docs-lead] |

## 11. Agent-readable outputs

<!-- Guidance: Decide how coding agents and assistants consume the docs. Questions: which pages are listed in llms.txt, which have Markdown mirrors, and how are they discovered? Pitfall: an llms.txt that lists HTML pages full of navigation chrome, or Markdown mirrors that drift from the HTML. Check the current proposal at llmstxt.org before implementing. -->

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.

| Item | Decision |
|---|---|
| Index file locations | `/llms.txt` for the whole site; [`/checkout/llms.txt`, `/orders/llms.txt`] for large areas. The proposal allows files at subpaths covering the URLs beneath them, and agents prefer the most specific one. |
| Sections in the index | One H2 per top-level area from section 3, plus an "Optional" section for archive, changelog history and long explanation pages that an agent may skip. |
| Markdown mirrors | Every published page has a Markdown version at the same URL with `.md` appended or replacing the extension; folder URLs use `index.md` or `index.html.md`. State which form you use: [form]. |
| Discovery from pages | Each HTML page carries `<link rel="alternate" type="text/markdown" href="...">` for its mirror and `<link rel="describedby" href="/llms.txt">` (or the more specific index). |
| Discovery by header | The same relations are sent as an HTTP `Link` header, configured at the server or CDN, so non-HTML resources are covered too. |
| Generation | Mirrors are generated from the same source files at build time, never edited by hand. |
| Content of mirrors | Main content only: no navigation, cookie banners or footers. Keep code blocks, tables and absolute links. |
| Versioning | Mirrors and `llms.txt` describe the current version only; archived versions are excluded. |
| Exclusions | [Pages excluded, for example internal previews, unsupported versions] |

*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

<!-- Guidance: Say how this IA is tested before launch and kept true after it. Questions: was the navigation tested with real readers, and what does the build enforce? Pitfall: an IA document that is approved once and then contradicted by the live site within a quarter. -->

### 12.1 Validation before launch

| Method | What it tests | Pass criterion |
|---|---|---|
| Card sort (open or closed) | Whether readers group topics the way the navigation does | Agreement threshold set by the team: [value] |
| Tree test | Whether readers find target pages in the text tree alone | Success rate per task: [target]; tasks below target are redesigned |
| First-click test on landing pages | Whether the "Start here" action is the first click | [Target] |
| Link and redirect check | No broken internal links; every legacy URL resolves | Zero failures |
| Accessibility check of navigation | Keyboard order, landmarks, skip link, visible focus, WCAG 2.2 AA | No failures on navigation templates |

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

| Change | Who decides | Record |
|---|---|---|
| New top-level item or URL pattern | Docs lead with product lead | New minor version of this document |
| New page type | Docs lead | Section 2.1 and templates updated |
| Page moves inside an area | Area owner | Redirect row and pull request |
| Annual IA review | Docs lead | Content Audit (`docs/content-audit`) findings feed this document |

## 13. Glossary and references

<!-- Guidance: Define terms readers of this specification may not share and list the sources used. -->

### 13.1 Glossary

| Term | Meaning in this document |
|---|---|
| Information architecture (IA) | The structure, labels, navigation and search design that let readers find and understand content |
| Diátaxis type | One of tutorial, how-to guide, reference or explanation |
| Page type | A local, enforced subtype of a Diátaxis type, with its own template |
| Landing page | A navigation page for an area or section folder |
| Canonical URL | The one URL search engines and links should use for a page |
| Markdown mirror | A Markdown version of a page served at a predictable URL for agents |
| `llms.txt` | A Markdown index of key pages intended for language models and agents |
| Tree test | A usability test of a navigation hierarchy without visual design |

### 13.2 References

| Reference | Version or date | Use in this document |
|---|---|---|
| Diátaxis, Daniele Procida, https://diataxis.fr/ | Living site, checked 2026-10-24 | Four documentation types and the two-question compass |
| llms.txt proposal, Jeremy Howard, https://llmstxt.org/ | Published 2024-09-03, modified 2026-08-10 | Index file format, Markdown mirrors, discovery relations |
| ISO/IEC/IEEE 26514:2022, Design and development of information for users, https://www.iso.org/standard/77451.html | Edition 1, 2022 | Structure, navigation and finding aids topics (structure only) |
| WCAG 2.2, W3C Recommendation, https://www.w3.org/TR/WCAG22/ | 2024-12-12 | Navigation accessibility target |
| [Internal SEO or web standard] | [Version] | [Use] |

## 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.