# Pathrule Pattern: Documentation Engineering (1.0.0)
# ::pathrule:package:documentation-engineering

### [RULE] Change documentation with the interface it describes  (path: /docs)
<!-- scope: folder | priority: medium | advisory -->

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.

- Name documentation paths in ownership and change templates for public APIs, commands, configuration, operations, and deprecations.
- Link hand-written claims to source code, schema, tests, or an authoritative external source so reviewers can verify them.
- Execute commands, snippets, links, and example projects in automation where practical; clearly mark outcomes that require manual evidence.
- Delete or redirect obsolete pages instead of leaving several apparently current answers.

Verification: Change a documented command, configuration key, response field, and runbook step in fixtures; confirm ownership and automated checks identify every affected page.

---

### [MEMORY] Each page serves one documentation need  (path: /docs)

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.

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.

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.

---

### [MEMORY] Examples are compatibility contracts  (path: /tests)

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.

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.

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.