From e1359ea22751f9fe0c5072bee3c536c29b32d48d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 9 Aug 2026 21:23:50 +0000 Subject: [PATCH] Adopt canonical documentation ownership policy --- docs/policy/documentation.md | 488 ++++++++++------------------------- 1 file changed, 140 insertions(+), 348 deletions(-) diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index f4f2105..5823977 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,356 +1,148 @@ -# Go Project Documentation Policy +# Documentation Policy ## Purpose -Project documentation must help four audiences: - -1. users who need to run the application; -2. administrators/operators who need to configure and operate it; -3. developers who need to understand and change it safely; -4. LLM coding agents that need clear scope, boundaries, and invariants. - -Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition. +This policy assigns each documentation topic to one canonical owner. Its goal is +to keep Narratio documentation accurate, concise, discoverable, and resistant +to drift for users, operators, developers, integrators, and LLM coding agents. ## Core Rules -### 1. Keep docs concise +### One Canonical Owner + +Each authoritative fact belongs in one document. A non-owning document may give +a short, stable summary for orientation, but it must link to the canonical owner +instead of repeating volatile details. + +Volatile details include commands, flags, configuration fields and defaults, +stage or integration keys, schemas, file names, paths, status codes, retry +behavior, and runtime guarantees. If readers could reasonably treat a statement +as a contract, maintain it only in the owning document. -Each document should cover a defined scope and only the essentials for that scope. +### Current And Future Behavior + +Outside `docs/roadmap/`, documentation describes implemented behavior only. +Partial features may be described only to their implemented boundary. + +ADRs are the narrow exception: an ADR may record an accepted architectural +decision before implementation, but acceptance must not be presented as proof +that the behavior exists. The roadmap owns implementation status and sequencing +until the decision is implemented. Current architecture, user, operator, +integration, and internal documentation are updated when the behavior lands. + +### Audience And Detail + +Write for the document's stated audience and include only the detail needed for +its owned topic. User and operator docs should not expose implementation detail. +Developer docs should link to user-facing and external contracts rather than +restate them. + +### Examples -Avoid: -- long background explanations; -- repeated reference material; -- implementation detail in user-facing docs; -- aspirational language outside roadmap docs; -- verbose examples where one minimal example is clearer. - -### 2. Document only implemented behavior outside roadmap files - -Unimplemented, planned, aspirational, experimental, or future work may be described only under: - -- `docs/roadmap/` - -No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist. - -If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary. - -### 3. Use canonical homes - -Each type of information should have one canonical location. - -Canonical homes: - -- project purpose and quickstart: `README.md` -- development principles: `docs/architecture.md` -- configuration reference: `docs/config.md` -- CLI reference: `docs/cli.md` -- operations and recovery: `docs/operations.md` -- troubleshooting: `docs/troubleshooting.md` -- implemented internals: `docs/internal/` -- future work: `docs/roadmap/` -- contributor workflow: `docs/development.md` -- copyable examples: `examples/` - -Other files should summarize briefly and link to the canonical source. - -### 4. Keep examples real - -Examples should be valid, maintained, and free of secrets. - -Where practical: -- example configs should load successfully; -- example commands should match real CLI syntax; -- important examples should be covered by tests. - -## Documentation Profiles - -All projects require: - -- `README.md` -- `docs/architecture.md` - -Additional docs depend on the project. - -### Small library - -Recommended: -- `docs/development.md`, if contributor conventions are non-obvious - -### Simple CLI - -Required: -- `docs/cli.md` - -Recommended: -- `docs/development.md` - -### Config-driven CLI - -Required: -- `docs/cli.md` -- `docs/config.md` - -Recommended: -- `examples/` -- `docs/development.md` - -### Stateful or operator-facing application - -Required: -- `docs/cli.md`, if CLI-based -- `docs/config.md`, if config-driven -- `docs/operations.md` - -Recommended: -- `docs/troubleshooting.md` -- `examples/` -- `docs/development.md` - -### Modular, staged, service-oriented, or orchestration application - -Required: -- `docs/cli.md`, if CLI-based -- `docs/config.md`, if config-driven -- `docs/operations.md` -- `docs/internal/` -- `docs/development.md` - -Recommended: -- `docs/troubleshooting.md` -- validated examples under `examples/` - -## Required Documents - -### README.md - -**Audience:** users, administrators, operators - -The README is the outward-facing project orientation page. - -It should include, in order: - -1. concise description; -2. elevator pitch; -3. shortest useful command or usage example; -4. links to targeted docs. - -The README should be short. It is not a manual. - -The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.) - -### docs/architecture.md - -**Audience:** developers, LLM coding agents - -`docs/architecture.md` is required for every project. - -It is an inward-facing development policy document. It should describe how the project is intended to be built and changed. - -It should include: - -- project shape; -- core design principles; -- package and boundary philosophy; -- state/persistence philosophy, if applicable; -- external integration philosophy, if applicable; -- error-handling and logging principles; -- testing expectations; -- documentation expectations; -- architectural invariants; -- explicit non-goals, if useful. - -For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light. - -### docs/config.md - -**Audience:** administrators, operators, advanced users - -Required for applications with configuration files. - -It should include, in order: - -1. config file locations and discovery precedence; -2. minimal working config; -3. production-oriented config; -4. full configuration reference; -5. secrets handling, if applicable; -6. links to maintained examples. - -The full configuration reference should be canonical. - -### docs/cli.md - -**Audience:** users, administrators, operators - -Required for CLI applications. - -It should include, in order: - -1. shortest useful command; -2. command overview; -3. complete flag reference; -4. common workflows; -5. diagnostic or recovery commands, if applicable. - -Explain when commands are useful, not just their syntax. - -### docs/operations.md - -**Audience:** administrators, operators - -Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures. - -It should cover: - -- normal workflow; -- filesystem layout; -- remote storage layout, if applicable; -- logs and manifests; -- resume/retry behavior; -- cleanup behavior; -- archive/backup behavior; -- safe recovery procedures; -- operational caveats. - -### docs/troubleshooting.md - -**Audience:** administrators, operators - -Recommended once recurring failure modes exist. - -Each entry should include: - -- symptom; -- likely cause; -- diagnostic command or inspection step; -- safe fix; -- relevant links. - -### docs/development.md - -**Audience:** developers, LLM coding agents - -Required for projects maintained by humans and LLM coding agents. - -It should include: - -- repository layout; -- build/test commands; -- coding conventions; -- dependency policy; -- how to add config fields; -- how to add CLI flags; -- how to add stages/modules/adapters, if applicable; -- how to update examples; -- documentation update expectations. - -### docs/internal/ - -**Audience:** developers, LLM coding agents - -Required for modular, staged, service-oriented, or orchestration projects. - -This directory describes implemented internal components. It is not the roadmap. - -Use one file per major component where useful. - -Each component doc should include: - -1. purpose; -2. inputs and outputs; -3. boundaries; -4. config fields used; -5. external adapters used; -6. state or manifest behavior, if applicable; -7. skip/resume behavior, if applicable; -8. failure behavior; -9. tests to inspect before changing; -10. architectural invariants. - -### docs/roadmap/ - -**Audience:** maintainers, developers, LLM coding agents - -This is the only place for planned, future, aspirational, experimental, or unimplemented work. - -Roadmap docs should clearly distinguish: - -- proposed work; -- accepted plans; -- deferred ideas; -- rejected ideas; -- implementation prompts or task breakdowns, if useful. - -Roadmap docs should not be confused with current behavior. - -### docs/integrations/ - -**Audience:** developers, LLM coding agents - -Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain. - -This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses. - -Use one file per integration where useful. - -## Examples Directory - -Projects with non-trivial configuration or workflows should include `examples/`. - -Useful examples include: - -- minimal working config; -- production-oriented config; -- full annotated config; -- local development config; -- remote/object-storage config; -- minimal session/input file. - -Examples should be valid, maintained, tested when practical, and linked from relevant docs. - -## Security and Privacy - -Docs and examples must not include: - -- real API keys; -- tokens; -- passwords; -- private keys; -- private environment dumps; -- sensitive user data; -- raw private transcripts; -- private infrastructure details unless intentionally public. - -Document secret-handling mechanisms, not actual secret values. - -## Maintenance Rules - -When docs change, verify the affected behavior. - -Where practical: - -- load example config files in tests; -- test CLI examples or command parser behavior; -- validate documented flags against real flags; -- remove stale references; -- update links after renames; -- keep roadmap content out of non-roadmap docs. - -If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs. - -Documentation is complete only when it matches the current code. - -## Documentation Change Checklist - -Before merging documentation changes, verify: - -- README is concise and orientation-focused. -- `docs/architecture.md` describes development principles. -- Future work appears only under `docs/roadmap/`. -- User-facing docs avoid unnecessary internals. -- Developer-facing docs preserve boundaries and invariants. -- Config examples match the schema. -- CLI examples match real commands and flags. -- Defaults appear in the canonical config reference. -- No secrets or private data are included. -- Links are accurate. +Complete copyable files belong in `examples/`. Documentation may use the +smallest illustrative snippet needed to explain its owned topic, but should link +to maintained examples instead of embedding a second complete copy. + +Examples must be valid, secret-free, and tested where practical. Commands and +configuration used in documentation should match the application. + +### Security And Privacy + +Documentation and examples must not contain real credentials, private keys, +private environment dumps, sensitive source material, or private infrastructure +details unless intentionally public. Document secret-handling mechanisms, not +secret values. + +## Canonical Ownership + +| Topic | Canonical owner | Owned content | Content owned elsewhere | +| --- | --- | --- | --- | +| Product orientation and minimal end-to-end quickstart | `README.md` | What Narratio is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. | +| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. | +| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. | +| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. | +| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. | +| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, output conventions, and exit behavior. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, stage implementation details. | +| Configuration contract | `docs/config.md` | Discovery and precedence, file schemas, fields, defaults, environment overrides, validation rules, and user-selectable stage or integration settings. | Complete example files, CLI syntax, runtime state lifecycle, implementation details. | +| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and remote-state layout, output and diagnostic handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical artifact schemas, implementation mechanics. | +| Troubleshooting | `docs/troubleshooting.md` | Symptom-driven diagnosis, likely causes, safe inspection steps and remedies, and links to relevant contracts. | CLI syntax, configuration definitions, operational procedures, integration contracts, implementation mechanics. | +| Public HTTP contract, if introduced | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. | +| Consumer guidance, if a public package or API is introduced | `docs/consumers/` | Task-oriented use of the public interface, minimal client examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. | +| External and durable integration contracts | `docs/integrations/` | External file formats and protocols, upstream and downstream contracts, logical artifact paths and schemas, media types, and compatibility behavior. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. | +| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. | +| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | +| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | +| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. | +| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. | + +Documents that do not exist are required only when the corresponding interface +or responsibility exists. Do not create placeholder API, consumer, integration, +or operations documents for behavior the application does not have. + +## Boundary Rules + +### Orientation + +The README owns product orientation. The developer guide routes contributors. +Architecture owns normative structure. Internal overview owns the current +concrete component map. These documents may link to one another but should not +maintain parallel package or behavior descriptions. + +### Commands, Configuration, Operations, And Troubleshooting + +CLI documentation answers how to invoke the application. Configuration +documentation answers what settings mean. Operations answers what happens to +runtime state and how to operate or recover the application. Troubleshooting +starts from observable symptoms and links readers to the owning command, +configuration, operational, or integration contract. When a workflow crosses +these topics, choose the document that owns the task and link to the other +contracts. + +### Contracts And Implementation + +Integration and API documents define externally observable shapes and +semantics. Internal documents explain how Narratio implements or consumes those +contracts. Internal docs may name a field, file, or protocol to identify a +dependency, but must link to its canonical contract for the definition. + +### Security Topics + +This policy owns what documentation and examples may contain. Architecture owns +application security invariants. Configuration owns credential-supply +mechanisms. Operations owns permissions and handling of sensitive runtime +artifacts. Troubleshooting owns safe diagnostic and remediation guidance. +Internal docs own implementation mechanisms only. + +## Architecture Decision Records + +Use sequentially numbered ADR filenames such as +`0001-record-architecture-decisions.md`. Follow the lightweight Nygard format: + +1. title; +2. status; +3. date; +4. context; +5. decision; +6. alternatives considered; +7. consequences. + +Treat the decision content of an accepted ADR as immutable. When a decision +changes, create a new ADR and update the earlier ADR's status to superseded. +Rejected architectural alternatives belong in the ADR; rejected product ideas +belong in the roadmap. + +## Maintenance + +When behavior changes, update its canonical owner in the same change. If +ownership moves, remove the old definition and replace it with a link where +navigation remains useful. + +Before completing documentation work: + +- verify affected behavior and examples; +- check commands, flags, fields, defaults, schemas, and paths against their + implementation; +- keep unimplemented behavior in the roadmap, subject to the ADR exception; +- remove stale references and validate links; +- confirm that non-owning documents summarize and link rather than redefine; +- confirm that no secrets or sensitive private data were added.