Skip to main content

Information Architecture Standard

A knowledge base only compounds if anyone — a person or an agent — can predict where a piece of content lives before they go looking, and where a new piece must go before they write it. This standard makes both predictable.

It rests on a single idea from faceted information architecture: pick one organizing axis for the top level, and express every other facet as links, not folders. When the top level answers three questions at once, the reader can't predict anything.

When to use this​

  • Placing new content — run Rule Set A, then B, then C.
  • Finding content — the same three rules tell you where to look.
  • Restructuring — any move of three or more files runs an inventory first, then these rules.

Rule Set A — Where content goes​

One question decides the top-level section: "What is this primarily about?"

The three facets​

  • Method — a capability or way of operating: how to think, decide, focus, and act. The reusable inner game.
  • Library — a body of subject knowledge: a domain anyone could study independently of us.
  • Operating — the operating system of the site itself: the standards it holds to and the way it keeps score.

Every top-level folder belongs to exactly one band. The bands are ordered (Method first, Library next, Operating last) so the flat top level still reads as a story from inner game to applied knowledge.

The placement test​

Ask the questions in order. The first yes picks the band.

  • Could someone at any organisation reuse this as a way of working? → Method
  • Is this knowledge about a domain, independent of how we operate? → Library
  • Does this define a standard, a score, or how the site runs? → Operating

If none fits, the content has no home here — it likely belongs in the rhetoric or our-situation layers, not the universal knowledge base. (See Documentation Writing Standard for the layer boundary.)

One thing per top folder​

A domain is not a dumping ground. If a top folder starts absorbing content that fails its own placement test — business operations filed under a technology label, industry analysis nested inside a protocol — that content gets lifted out to its own peer, not buried deeper. Semantic clarity at the top level is the whole point, and it is also what answer engines reward (Rule Set D).

Rule Set B — How each folder is shaped​

Folder-as-function​

A function is a folder with a landing page — never a loose file sitting at a section root. If you are tempted to drop pricing.mdx directly into a section, you actually have a pricing/ function: give it a folder and an index landing.

  • Every folder carries a category descriptor (label + ordering position).
  • Every folder carries an index landing page — the hub that orients the reader and links its children.
  • The only file allowed at a function root is its index.

Depth cap​

Keep nesting to four levels or fewer below the docs root (convention — beyond this, readers and crawlers lose the thread, and URLs become fragile). If you need a fifth level, you have found a function that deserves to be promoted to a peer.

The 5P pillars (Library: business and industry functions)​

A business or industry function decomposes into five pillars — a domain-native answer to "what are the doc-types here":

  • principles — the first principles the function rests on
  • performance — the metrics and thresholds that gauge it (numeric thresholds carry a source or a *heuristic* marker — see Documentation Writing Standard)
  • platform — the tools and infrastructure it runs on
  • process — how the work is actually done, step by step
  • players — the ecosystem actors: the society-level participants who engage with this industry (ecosystem). Those players have roles and positions internally — a level deeper, not the same pillar.

Note: existing content uses players as the canonical filename (e.g. players.mdx, robotics-players/). This matches the pillar. The earlier name positions was a narrower lens and is now an accepted variant pointing to the same pillar.

Method and science content is narrative, not operational — it uses the doc-type map in Rule Set C instead of forcing the 5P shape.

Rule Set C — Format and action by job-to-be-done​

This is the rule that tells you, by what you are trying to do, the right doc-type, file, format, and authoring action. The doc-types follow the Diátaxis model (tutorials, how-to, reference, explanation).

Job to be doneDoc-typeFileFormatAuthoring action
Explain a concept and why it mattersExplanation{concept}.mdxAnswer-first sentence → when/problem → detailCoach voice; teach the pattern
Teach a procedureHow-toprocess.mdxNumbered, verifiable stepsCoach voice; one outcome per step
Let a reader look up specs or parametersReferenceplatform.mdx · players.mdxSpec lists / genuine data tablesPrecise, no narrative
State a domain's first principlesExplanationprinciples.mdxPrinciple → rationale → consequenceFirst-principles voice
Report metrics of a functionReferenceperformance.mdxThresholds with source or *heuristic*Honest disclosure of every number
Orient a reader at a section or functionHubindex.mdxAnswer-first overview + child linksMap the territory, then route

Format hard-rules​

  • Prefer .mdx — it compiles to components, so a page can carry diagrams and interactive structure, not just prose.
  • Plain .md is acceptable only for pure prose with no visual structure.
  • Never author a knowledge-base page as a presentational component file — it breaks search indexing. Pages explain; components are imported into pages.
  • No loose files at a function root (Rule Set B).

Rule Set D — Answer Engine Optimization​

The knowledge base is read as much by answer engines as by people. AEO is not a separate task — it is the natural result of following A, B, and C, plus four habits.

  • Answer-first. Open every page with one or two sentences that directly answer the question the title implies. People skim it; engines quote it.
  • Self-contained sections. Each heading-and-body chunk should make sense lifted out on its own — that is the unit an engine retrieves.
  • Semantic URLs. Because the top level is one clean facet (Rule Set A) and depth is capped (Rule Set B), the path itself describes the content. A clear path outranks a buried one.
  • Descriptive frontmatter. Every page sets a title and a description — the description is the snippet an engine shows.
  • Question-shaped headings where natural — they match the queries readers actually type.
  • Clean hierarchy. One H1, ordered H2/H3, no skipped levels — the structure an engine parses to build context and breadcrumbs.

The Structure as a Thinking Instrument​

Following Rules A–D does more than keep the folder tidy. It turns the folder tree itself into a gap-radar — a matrix you can read without opening a single page.

Function × 5P is a coverage matrix​

Every industry hub is a row. The five pillars are columns. An empty cell is a located content gap — not a vague "we should write more," but a specific missing pillar in a named function.

This is matrix thinking applied to the knowledge base: lay capability against demand, find where value is absent. The live <PillarCoverage> strip on each industry hub renders this matrix in context — green cells are present, highlighted cells are gaps visible to the reader before they scroll.

Method → Library → Operating is a first-principles decomposition​

The band order is not alphabetical convenience. It follows the sequence of understanding: inner game first (how to think and decide), then applied knowledge (what a domain contains), then operating system (how this site governs itself). A reader who works through the bands in order moves from reusable mental models to domain specifics to the standards that govern both. The structure teaches before the content does.

Anchoring a new domain against an existing one surfaces gap classes​

When onboarding a new industry or function, map it against one that is already fully populated. Four gap classes emerge:

  • Direct mapping — the new domain has the same pillar shape; populate and link.
  • Different model — the pillar exists but the domain's version of it diverges from the general pattern; note the variance.
  • Absence — the pillar is genuinely missing and needs to be written.
  • Genuinely new — the domain introduces a pillar type not in the 5P schema; propose an extension.

This anchoring method is the practical application of knowledge-base schema meta-learning: new domains do not start from scratch, they start from the gap map of an existing one.

The whole standard in one pass​

When you place or write a page:

  1. Where — run the placement test → Method · Library · Operating (Rule A).
  2. Shape — folder-as-function, an index hub, depth ≤ 4, 5P for business/industry (Rule B).
  3. Format — pick the doc-type by your job-to-be-done; that fixes the file and format (Rule C).
  4. Reach — answer-first, self-contained, semantic URL, full frontmatter (Rule D).

If you cannot answer step 1, the content does not belong in the knowledge base. If you cannot answer step 3, you do not yet know what the page is for.

Connection​