eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Adopt canonical documentation ownership policy

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-09 21:23:50 +00:00
parent 7fdd99ec27
commit e1359ea227
1 changed files with 140 additions and 348 deletions
Download Patch File Download Diff File Expand all files Collapse all files

488
docs/policy/documentation.md
View File

@@ -1,356 +1,148 @@
# Go Project Documentation Policy # Documentation Policy
## Purpose ## Purpose
Project documentation must help four audiences: This policy assigns each documentation topic to one canonical owner. Its goal is
to keep Narratio documentation accurate, concise, discoverable, and resistant
1. users who need to run the application; to drift for users, operators, developers, integrators, and LLM coding agents.
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.
## Core Rules ## 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: Complete copyable files belong in `examples/`. Documentation may use the
- long background explanations; smallest illustrative snippet needed to explain its owned topic, but should link
- repeated reference material; to maintained examples instead of embedding a second complete copy.
- implementation detail in user-facing docs;
- aspirational language outside roadmap docs; Examples must be valid, secret-free, and tested where practical. Commands and
- verbose examples where one minimal example is clearer. configuration used in documentation should match the application.
### 2. Document only implemented behavior outside roadmap files ### Security And Privacy
Unimplemented, planned, aspirational, experimental, or future work may be described only under: Documentation and examples must not contain real credentials, private keys,
private environment dumps, sensitive source material, or private infrastructure
- `docs/roadmap/` details unless intentionally public. Document secret-handling mechanisms, not
secret values.
No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
## Canonical Ownership
If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
| Topic | Canonical owner | Owned content | Content owned elsewhere |
### 3. Use canonical homes | --- | --- | --- | --- |
| 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. |
Each type of information should have one canonical location. | 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. |
Canonical homes: | 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. |
- project purpose and quickstart: `README.md` | 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. |
- development principles: `docs/architecture.md` | 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. |
- configuration reference: `docs/config.md` | 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. |
- CLI reference: `docs/cli.md` | 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. |
- operations and recovery: `docs/operations.md` | 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. |
- troubleshooting: `docs/troubleshooting.md` | 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. |
- implemented internals: `docs/internal/` | 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. |
- future work: `docs/roadmap/` | 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. |
- contributor workflow: `docs/development.md` | 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. |
- copyable examples: `examples/` | 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. |
Other files should summarize briefly and link to the canonical source. | Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. |
### 4. Keep examples real Documents that do not exist are required only when the corresponding interface
or responsibility exists. Do not create placeholder API, consumer, integration,
Examples should be valid, maintained, and free of secrets. or operations documents for behavior the application does not have.
Where practical: ## Boundary Rules
- example configs should load successfully;
- example commands should match real CLI syntax; ### Orientation
- important examples should be covered by tests.
The README owns product orientation. The developer guide routes contributors.
## Documentation Profiles Architecture owns normative structure. Internal overview owns the current
concrete component map. These documents may link to one another but should not
All projects require: maintain parallel package or behavior descriptions.
- `README.md` ### Commands, Configuration, Operations, And Troubleshooting
- `docs/architecture.md`
CLI documentation answers how to invoke the application. Configuration
Additional docs depend on the project. documentation answers what settings mean. Operations answers what happens to
runtime state and how to operate or recover the application. Troubleshooting
### Small library starts from observable symptoms and links readers to the owning command,
configuration, operational, or integration contract. When a workflow crosses
Recommended: these topics, choose the document that owns the task and link to the other
- `docs/development.md`, if contributor conventions are non-obvious contracts.
### Simple CLI ### Contracts And Implementation
Required: Integration and API documents define externally observable shapes and
- `docs/cli.md` semantics. Internal documents explain how Narratio implements or consumes those
contracts. Internal docs may name a field, file, or protocol to identify a
Recommended: dependency, but must link to its canonical contract for the definition.
- `docs/development.md`
### Security Topics
### Config-driven CLI
This policy owns what documentation and examples may contain. Architecture owns
Required: application security invariants. Configuration owns credential-supply
- `docs/cli.md` mechanisms. Operations owns permissions and handling of sensitive runtime
- `docs/config.md` artifacts. Troubleshooting owns safe diagnostic and remediation guidance.
Internal docs own implementation mechanisms only.
Recommended:
- `examples/` ## Architecture Decision Records
- `docs/development.md`
Use sequentially numbered ADR filenames such as
### Stateful or operator-facing application `0001-record-architecture-decisions.md`. Follow the lightweight Nygard format:
Required: 1. title;
- `docs/cli.md`, if CLI-based 2. status;
- `docs/config.md`, if config-driven 3. date;
- `docs/operations.md` 4. context;
5. decision;
Recommended: 6. alternatives considered;
- `docs/troubleshooting.md` 7. consequences.
- `examples/`
- `docs/development.md` 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.
### Modular, staged, service-oriented, or orchestration application Rejected architectural alternatives belong in the ADR; rejected product ideas
belong in the roadmap.
Required:
- `docs/cli.md`, if CLI-based ## Maintenance
- `docs/config.md`, if config-driven
- `docs/operations.md` When behavior changes, update its canonical owner in the same change. If
- `docs/internal/` ownership moves, remove the old definition and replace it with a link where
- `docs/development.md` navigation remains useful.
Recommended: Before completing documentation work:
- `docs/troubleshooting.md`
- validated examples under `examples/` - verify affected behavior and examples;
- check commands, flags, fields, defaults, schemas, and paths against their
## Required Documents implementation;
- keep unimplemented behavior in the roadmap, subject to the ADR exception;
### README.md - remove stale references and validate links;
- confirm that non-owning documents summarize and link rather than redefine;
**Audience:** users, administrators, operators - confirm that no secrets or sensitive private data were added.
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.