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

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.

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.