Documentation

TL;DR

Documentation is an active product surface. Wordloop docs are the canonical source for durable engineering knowledge; agent skills are the execution layer that selects, loads, and applies that knowledge safely. We design documentation for humans and AI agents at the same time, organise it with Diátaxis, expose it through llms.txt, Markdown exports, and MCP, and enforce freshness with automation wherever a human would drift.

Why this matters

In 2026, documentation is part of the runtime environment for engineering work. A human reads the site through navigation and search; an agent reads the same knowledge through MCP resources, llms.txt, llms-full.txt, and per-page Markdown exports. If those surfaces disagree, the system teaches different readers different truths. That is not a documentation problem; it is an engineering defect.

The operating model is simple: docs hold the knowledge, skills control the agent behaviour. Durable guidance belongs in the docs site where humans and agents can inspect it. Skill files stay concise and directive: they define when to trigger, what context to load, which tools to use, and which safety checks must run. This keeps prompts lean, reduces duplicated policy, and gives us one canonical place to correct factual drift.

Our principles

1. Documentation is canonical knowledge

Architecture principles, service handbooks, workflow guides, glossary terms, ADRs, API references, and generated schemas belong in the docs site. A skill may point to these pages, but it does not become the source of truth for material that humans also need to understand.

2. Skills are the agent execution layer

Agent skills are a control surface, not a second documentation site. A skill owns triggering, task routing, tool use, safety constraints, verification steps, and context-loading instructions. It should say, for example, "read the App service handbook before changing wordloop-app data fetching," not duplicate the handbook in full.

3. AI-native documentation is first class

Every important documentation surface must survive machine consumption. We publish llms.txt as the curated index, llms-full.txt as the consolidated corpus, .md exports for individual pages, and MCP resources for structured retrieval. Agent-readiness is not an afterthought or an SEO trick; it is a quality attribute of the docs system.

4. Diátaxis is the structural frame

We organise by reader intent, not by our internal org chart. Tutorials teach, how-to guides solve, reference pages support lookup, and explanation pages build understanding. A page that mixes these jobs forces both humans and agents to infer the purpose from context, which makes retrieval weaker and maintenance harder.

5. Active docs replace passive docs

A page is not "done" when it is written. Active docs declare ownership, review cadence, freshness status, and source-of-truth boundaries. Pages that age past their review window are visibly flagged and reviewed as part of normal engineering work, not as a cleanup project.

6. Automation is the first reviewer

Automated checks enforce the cheap, high-signal rules: required frontmatter, broken internal links, stale review dates, invalid skill-to-doc references, stale generated corpora, and known version mismatches. Humans review accuracy, judgment, and usefulness. Automation handles the facts it can verify without fatigue.

7. Prefer generated reference over prose

API specs, event contracts, database schemas, CLI command tables, and error catalogues have machine-readable sources. We render them from those sources instead of hand-writing reference pages. Hand-written reference material drifts; generated reference material can be rebuilt and checked.

8. Decisions are append-only

Hard-to-reverse decisions live in ADRs. Accepted ADRs are not edited to match current preference; they are superseded. Each ADR carries enough consequence and debt context for a future reader to understand why the decision existed, what it cost, and when to revisit it.

9. Metadata interoperability matters

Formal documentation standards are useful when they sharpen interoperability discipline. ISO/PAS 25955:2026 is a Publicly Available Specification for Data Documentation Initiative interoperability, not a generic agent-documentation linking standard. The lesson we apply is precise metadata, stable identifiers, and explicit relationships between documentation objects. For agent discovery specifically, Wordloop uses llms.txt, Markdown exports, MCP resources, and HTTP Link headers.

10. Drift is corrected at the source

When code, docs, skills, specs, and design records disagree, we identify the source of truth before editing. Code and generated contracts win for shipped runtime behaviour. ADRs win for historical decisions. Active design docs win for current delivery intent until the shipped system proves otherwise. Skills win for agent execution behaviour only.

Freshness model

See Documentation Freshness for the operational policy.

How we apply this

• llms.txt and llms-full.txt are the machine-readable entry points.
• Agent-Native Systems defines the broader interface discipline for agent consumers.
• Keep Docs and Skills in Sync defines the change workflow for canonical docs and skill files.
• Correct Documentation Drift defines the triage workflow when docs, skills, code, specs, and design records disagree.
• Decisions records architectural decisions with append-only history.
• Reference contains generated and lookup-oriented material.

Anti-patterns we reject

• Skill files as shadow docs. A skill that duplicates durable engineering policy becomes stale faster than the canonical docs page.
• Docs pages as prompts. Documentation should explain systems and decisions; skills should instruct agents how to act.
• Documentation as an afterthought. Docs ship with the feature or the feature is incomplete.
• Manual reference tables. If a table can be generated from code, contracts, or schemas, generate it.
• Unowned pages. A page without owner and review cadence has no maintenance path.
• Stale diagrams. A diagram that does not match the system is worse than no diagram because it creates false confidence.
• Screenshots as reference. Screenshots are acceptable as evidence in incidents, not as canonical UI or architecture documentation.
• Marketing-flavoured engineering docs. Assertions need evidence, examples, or source-of-truth links.
• Overstated standards claims. Distinguish formal standards from emerging conventions. Name the standard, its scope, and why it applies.

Further reading

• Diátaxis — the structural model for tutorials, how-to guides, reference, and explanation.
• llms.txt — the emerging convention behind our AI-readable documentation index.
• Model Context Protocol — the protocol we use for structured agent access to docs resources and tools.
• ISO/PAS 25955:2026 — DDI interoperability specification; useful as a metadata-interoperability reference, not as an agent-discovery standard.
• Docs for Developers, Bhatti et al. — practical guidance for engineering documentation.
• Living Documentation, Cyrille Martraire — using code and automation to reduce documentation drift.