Documentation Engineering
Pathrule1 Rule • 2 Memories
Documentation engineering keeps knowledge useful by assigning each page a user task, content type, owner, source of truth, validation method, and review trigger. This bundle separates tutorials, how-to guides, reference, and explanation while linking docs to executable evidence and code changes. Unlike Code Review, it governs the maintained knowledge interface rather than the review of implementation changes.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
docs/
Change documentation with the interface it describes
Each page serves one documentation need
tests/
Examples are compatibility contracts
Rules
1Change documentation with the interface it describes/docsmediumadvisoryA code or configuration change updates every affected guide, reference, example, runbook, and generated artifact in the same review.
| 1 | A code or configuration change updates every affected guide, reference, example, runbook, and generated artifact in the same review. Deferring docs creates a period where the official path instructs users or operators to run behavior the system no longer supports. Enforce this boundary in /docs so invalid work stops before it reaches another subsystem or creates an externally visible side effect. |
| 2 | |
| 3 | - Name documentation paths in ownership and change templates for public APIs, commands, configuration, operations, and deprecations. |
| 4 | - Link hand-written claims to source code, schema, tests, or an authoritative external source so reviewers can verify them. |
| 5 | - Execute commands, snippets, links, and example projects in automation where practical; clearly mark outcomes that require manual evidence. |
| 6 | - Delete or redirect obsolete pages instead of leaving several apparently current answers. |
| 7 | |
| 8 | Verification: Change a documented command, configuration key, response field, and runbook step in fixtures; confirm ownership and automated checks identify every affected page. |
Memories
2Each page serves one documentation need/docsTutorials support learning, how-to guides complete a task, reference describes the system, and explanation builds understanding; mixing them hides the answer each reader needs.
| 1 | Tutorials support learning, how-to guides complete a task, reference describes the system, and explanation builds understanding; mixing them hides the answer each reader needs. Choose the primary need before writing and structure navigation so readers can move between the four types without repeating the same content. |
| 2 | |
| 3 | Keep tutorials safe and staged rather than exhaustive. Make how-to guides goal-oriented with prerequisites and verification. Generate reference from source where possible and reserve explanation for tradeoffs, rationale, and boundaries. Keep the decision explicit at /docs; moving it into an incidental caller makes behavior depend on which route happened to execute first. |
| 4 | |
| 5 | See /src for source-of-truth links and /tests for executable examples. That related boundary consumes this decision and carries the evidence that proves it still holds. |
Examples are compatibility contracts/testsUsers copy examples more often than prose, so a compiling but unexecuted snippet can still encode unsafe, incomplete, or obsolete behavior.
| 1 | Users copy examples more often than prose, so a compiling but unexecuted snippet can still encode unsafe, incomplete, or obsolete behavior. Store substantial examples as tested fixtures or small projects and import their rendered form into docs when tooling permits. |
| 2 | |
| 3 | Run examples against supported versions and validate their observable result, not just syntax. Include failure handling, cleanup, authentication, and production constraints that a copied happy path needs. Retire examples with the interface they teach and keep versioned docs only where users still operate that version. Keep the decision explicit at /tests; moving it into an incidental caller makes behavior depend on which route happened to execute first. |
| 4 | |
| 5 | See /docs for reader context and the release management pattern for versioned change. That related boundary consumes this decision and carries the evidence that proves it still holds. |
Why this pattern
Agents write one page for several audiences, copy facts from code without a source link, and update implementation while commands, examples, and runbooks silently decay.
Built for Teams maintaining developer guides, operational runbooks, API references, and architectural explanation.
Keeps your assistant from:
- Pages mixing learning, task, reference, and explanation goals
- Examples and commands that are never executed in CI
- Documentation with no owner, review trigger, or removal path
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-08-25