notarius/docs/policy/documentation.md

Documentation Policy

Purpose

This policy assigns each documentation topic to one canonical owner. Its goal is to keep Notarius documentation accurate, concise, discoverable, and resistant to drift for users, operators, developers, integrators, and LLM coding agents.

Core Rules

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, module 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.

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

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 Notarius 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.
CLI contract	docs/cli.md	Commands, arguments, flags, invocation semantics, and exit codes.	End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details.
Configuration contract	docs/config.md	Discovery and precedence, file schema, fields, defaults, environment overrides, validation rules, and user-selectable module or validator keys.	Complete example files, CLI syntax, runtime state lifecycle, module implementation details.
Operations	docs/operations.md	Runtime workflows, physical filesystem and state layout, diagnostics use, retention, resume, cleanup, permissions, recovery, and operational limits.	CLI flag syntax, configuration field definitions, logical output schemas, 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 output bundle 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, And Operations

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. 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 Notarius 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. 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.