weatherreporter/docs/policy/documentation.md

# Documentation Policy

## Purpose

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

## Core Rules

### One Canonical Documentation Owner

Each authoritative fact belongs in one canonical document or documentation
area. A non-owning document may give a short, stable summary for orientation,
but it must link to the canonical owner instead of maintaining a second
definition.

Volatile details include commands, flags, configuration fields and defaults,
report and module IDs, schemas, file names, paths, status and exit behavior,
retry behavior, and runtime guarantees. If readers could reasonably treat a
statement as a contract, its exact documentation belongs with the owner named
in this policy.

Executable sources of truth and documentation owners serve different purposes.
Code, schemas, and embedded assets determine runtime behavior. The canonical
document owns the corresponding explanation or reference for readers. Both may
necessarily express the same contract, but other documentation should summarize
and link rather than create another complete reference. When implementation and
documentation disagree, verify the intended behavior and update them together.

### Current State, Decisions, And Future Work

Outside `docs/roadmap/`, documentation describes implemented behavior only.
Partial features may be described only to their implemented boundary.

An accepted architecture decision may describe an approved direction before it
is implemented, but acceptance is not evidence that the behavior exists.
Current-state documents change when the implementation lands. Temporary
roadmaps own future work, sequencing, and implementation status; they do not
replace durable policies, decisions, or current contracts.

### Audience And Detail

Write for the document's stated audience and include only the detail needed for
its owned topic. User and operator documentation should not expose incidental
implementation detail. Developer documentation should link to user-facing and
external contracts instead of restating them.

### Links

Use descriptive link text and repository-relative links for repository
documents. Link to the canonical owner rather than to a duplicate summary.
Check every added or changed link, and repair or remove links when their target
moves or is retired.

### Examples And Code Fences

Complete copyable files belong in `examples/` when maintained examples exist.
Documentation may use the smallest illustrative snippet needed for its owned
topic, but should link to a maintained example instead of embedding a second
complete copy.

Examples must be valid, secret-free, and tested where practical. Commands,
flags, configuration, imports, and Go snippets must match implemented behavior.
Use a language tag on fenced code blocks, and identify fragments that are
illustrative rather than directly runnable.

### 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 quickstart | `README.md` | What Weatherreporter is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, architecture, and implementation detail. |
| Contributor workflow and package inventory | `docs/development.md` | Repository layout, local workflow, validation commands, coding conventions, task-specific change guidance, dependency workflow, and repository hygiene. | Architectural invariants, user-facing contracts, detailed subsystem behavior, and future work. |
| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, package boundaries, invariants, safety properties, and non-goals. | Concrete implementation mechanics, contributor procedures, decision history, and future work. |
| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and document lifecycle. | Application architecture and runtime behavior. |
| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, stable test boundaries, doubles, coverage guidance, regression policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
| Release procedure | `docs/release.md` | Version policy, release preparation, validation, tagging, automated publication, verification, failure handling, and release ordering. | General contributor workflow, product contracts, release-specific change summaries, and implementation history. |
| Release notes | `docs/releases/` | One versioned, changelog-style summary for each release, including compatibility and operator action. The file at the tagged commit supplies the corresponding Gitea release body. | Current CLI, configuration, operations, integration, architecture, and internal contracts; release procedure; implementation plans. |
| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, stdout and stderr behavior, summaries, and exit behavior. | Configuration field definitions, complete operating procedures, runtime filesystem layout, and command implementation. |
| Configuration contract | `docs/config.md` | Discovery and precedence, fields, defaults, secrets, validation rules, and user-selectable values. | Complete example files, CLI syntax, runtime state lifecycle, and loading implementation. |
| Operations | `docs/operations.md` | Normal workflows, physical workspace layout, artifacts and metadata, inspection, notification behavior, recovery, cleanup, permissions, and operational caveats. | Complete CLI syntax, configuration field definitions, logical external contracts, and implementation mechanics. |
| Troubleshooting | `docs/troubleshooting.md` | Recurring symptoms, likely causes, diagnostic steps, safe fixes, and links to normal-operation references. | Complete command and configuration references, routine operating procedures, and implementation detail. |
| Report template surface | `docs/templates.md` | Implemented template files and partials, render-context fields, editing rules, and maintainer-facing template examples. | Weather derivation, module implementation, generated-text validation internals, and operator procedures. |
| External and durable integration contracts | `docs/integrations/` | Weather API, Promptkit, Distributor, external formats and protocols, durable logical paths and schemas, compatibility behavior, and upstream or downstream responsibilities. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, and configuration defaults. |
| Internal subsystem behavior | `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, user-facing contracts, external schemas, operator procedures, and future package plans. |
| Architectural decision history | `docs/adr/`, when repository-local decisions require records | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, and task sequencing. |
| Temporary feature roadmaps | `docs/roadmap/`, while planned work needs coordination | Proposed, accepted, deferred, or rejected work; sequencing; gates; implementation status; and task breakdowns. | Implemented behavior reference and durable decision rationale. |
| Complete copyable artifacts | `examples/` | Maintained configuration and other files intended to be copied or run. | Field-by-field reference, command reference, and prose explanation. |

Conditional owners do not require placeholder files or directories. If
Weatherreporter introduces a new public API, consumer interface, release
process, or other durable documentation responsibility, update this policy to
assign its canonical owner when that responsibility is introduced.

## Boundary Rules

### Orientation, Architecture, And Internals

The README owns product orientation. The development policy routes contributors
and owns the concise current package inventory. Architecture owns normative
structure and invariants. Focused internal documents own implementation
behavior. These documents may link to one another but must not maintain
parallel package or behavior references.

### Commands, Configuration, Operations, And Troubleshooting

CLI documentation answers how to invoke Weatherreporter and what its command
interface does. Configuration documentation answers what settings mean.
Operations answers what happens to runtime state and how to operate or recover
the application. Troubleshooting starts from a symptom and leads to diagnosis
and a safe fix.

When a workflow crosses these topics, place the complete procedure with the
document that owns the task and link to the other contracts. Do not duplicate
complete flag, field, or path references to make a workflow self-contained.

### Templates, Integrations, And Implementation

Template documentation defines the maintainer-facing rendering surface.
Integration documentation defines externally observable shapes, logical paths,
protocols, and compatibility behavior. Internal documentation explains how
Weatherreporter produces, transforms, or consumes those contracts.

Internal documents may name a command, field, template value, path, or protocol
to identify a dependency, but must link to its canonical documentation for the
complete definition.

### Release Procedure And Release Notes

The release procedure owns how a maintainer prepares, publishes, verifies, and
recovers from a Weatherreporter release. Release notes under `docs/releases/`
own the concise historical summary for one version and are the checked-in
source for its generated Gitea release body.

Release notes are not current-state reference documents. They may summarize
what changed and link to durable documentation, but they must not become a
second command, configuration, operations, integration, architecture, or
internal reference. Correct the applicable canonical owner in the same change
when a release changes an implemented contract.

The release note at a published tag and the Gitea release generated from it are
historical records. Later corrections on `main` do not rewrite that published
record. Material release errors require the failure handling defined by the
release procedure rather than moving a published tag or overwriting its
release.

### Executable Authority

CLI parsing and help generation are the executable authority for accepted
commands and flags. Configuration structs, defaults, loading, and validation
are the executable authority for configuration behavior. Schemas and embedded
assets are the executable authority for validated formats and template
execution. Tests protect selected contracts and invariants but do not become a
second documentation reference merely by asserting them.

Canonical documentation must be checked against these authorities whenever the
corresponding behavior changes.

### Security Topics

This policy owns what documentation and examples may contain. Architecture owns
application security boundaries and invariants. Configuration owns
credential-supply mechanisms. Operations owns permissions and handling of
sensitive runtime artifacts. Integration documents own consumer-visible
security contracts. Internal documents 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.

Use one of these statuses:

- **Proposed:** the decision is under consideration and may change;
- **Accepted:** the decision is approved, whether or not implementation is
  complete;
- **Rejected:** the proposed decision was considered and not adopted;
- **Superseded:** a later accepted ADR replaces the accepted decision.

A proposed ADR transitions to Accepted or Rejected. An Accepted ADR transitions
to Superseded only when a later Accepted ADR replaces it. An ADR may be created
as Accepted when the decision has already been made.

Treat the decision content of an Accepted ADR as immutable. A changed decision
requires a later ADR rather than a rewrite of the accepted record. A Superseded
ADR must link to its replacement, and the replacement must link back. Rejected
architectural alternatives belong in the ADR; rejected feature ideas belong in
a roadmap when they need to be retained.

## Document Lifecycle

Create durable current-state documentation with the implementation it
describes. Update its canonical owner in the same change when behavior changes.
If ownership moves, remove the old definition and leave a link where navigation
remains useful.

Roadmaps are temporary coordination documents. When their work is complete,
record completion, move any still-useful decisions or contracts to their
durable owners, update incoming links, and archive or remove the roadmap
according to repository practice. Do not preserve completed roadmaps as a
second current-state reference.

Release notes are durable historical summaries rather than temporary roadmaps.
Keep them concise, retain them after publication, and keep current contracts in
their canonical owners.

Before completing documentation work:

- verify affected behavior and examples;
- check commands, flags, fields, defaults, schemas, paths, and identifiers
  against their implementation;
- keep unimplemented behavior in a roadmap, subject to the ADR exception;
- validate links and fenced examples;
- confirm non-owning documents summarize and link rather than redefine;
- remove stale or unsupported claims; and
- confirm that no secrets or sensitive private data were added.