ConfigKit/docs/policy/documentation.md

# Documentation Policy

**Base Policy Version:** 1.0

**Last Updated:** 2026-09-06

## Purpose

Assign each documentation topic one canonical owner so ConfigKit's documentation
remains accurate and useful to consumers, maintainers, and implementation agents.

## Core rules

### One canonical owner

Each authoritative fact belongs in one owning document or Go declaration's
reference documentation. Other documents may summarize and link to that owner;
they must not maintain competing definitions of commands, API contracts, YAML
semantics, defaults, paths, diagnostics, or compatibility guarantees.

### Policies, current behavior, and future work

- Policies state currently binding contributor rules, including constraints on
  future implementation. They do not imply that features already exist.
- Current API/configuration contracts, consumer guidance, and component
  documentation describe implemented behavior only, including partial boundaries.
- ADRs record accepted decisions and rationale. Acceptance is not evidence of
  implementation; execution status belongs in roadmaps.
- Roadmaps own unimplemented targets, deferred work, and execution status.

The initial target and implementation plan have separate owners. Do not put
staged steps or progress in `docs/roadmap/initial.md`. `docs/roadmap/implementation.md` owns those details.
As behavior lands, move its normative definition into the current contract and
replace the roadmap definition with a link. Retire completed roadmap material
as part of release preparation; ADRs preserve significant decision history.

### Audience and examples

Consumer documentation explains how to use the library and what consumers own.
Internal documents explain mechanisms and dependencies. Keep implementation
mechanics out of consumer guidance unless they affect a meaningful choice.

Complete copyable artifacts belong in `examples/`; Go API examples may live in
executable Go example tests beside the relevant package. Prose should use the
smallest useful excerpt and link to the maintained artifact. Examples must be
secret-free and checked against implemented behavior. Clearly label illustrative
future syntax in roadmaps; do not present it as a runnable current example.

### Security and privacy

Do not include real credentials, private keys, environment dumps, sensitive input,
or private infrastructure details unless intentionally public. Document secret
handling, not secret values.

## Canonical ownership

| Topic | Owner | Boundary |
| --- | --- | --- |
| Product orientation | `README.md` | Current status, purpose, navigation, and a minimal working example once available |
| Contributor entry point | `docs/development.md` | Reading guide and actual baseline validation commands |
| Architecture rules | `docs/policy/architecture.md` | Responsibilities, dependency constraints, invariants, and scope boundaries |
| Documentation rules | `docs/policy/documentation.md` | Ownership and document lifecycle |
| Testing rules | `docs/policy/testing.md` | Risk-based sufficiency, test boundaries, and maintenance principles |
| Release rules | `docs/policy/release.md` | Compatibility, integrity, gates, immutability, and exceptions |
| Release procedure | `docs/release.md`, when operational | Exact maintainer commands, prerequisites, supported targets, and verification |
| Exported Go API | Go documentation beside declarations | Symbol contracts, errors, ownership, and lifecycle API behavior |
| YAML and resolution semantics | `docs/config.md`, as behavior lands | Syntax, composition, precedence, conversion, secret references/bootstrap, and explanation semantics; Go reference docs link here for shared rules |
| Consumer walkthroughs | `docs/consumers/`, when useful | Task-oriented usage and consumer responsibilities, not duplicate API reference |
| Component inventory | `docs/internal/overview.md` | Implemented components and links to their owners |
| Component mechanics | Other `docs/internal/` files, when needed | Detailed implementation behavior and change recipes |
| Architectural decisions | `docs/adr/` | Context, decisions, alternatives, consequences, and supersession history |
| Initial target | `docs/roadmap/initial.md` | Unimplemented end-state and deferred feature scope |
| Implementation plan | `docs/roadmap/implementation.md` | Stages, dependencies, acceptance gates, and progress |
| Release readiness gaps | `docs/roadmap/release-readiness.md` | Outstanding release prerequisites and closure evidence |
| Historical release notes | `docs/releases/` | Version-specific historical summaries required by release policy |
| Complete examples | `examples/` and executable Go examples | Maintained artifacts; prose links instead of duplicating full examples |

A listed future owner is not a requirement to create an empty file now. Create
API, consumer, example, and component documents when the corresponding behavior
exists and there is useful content to own. Link only to existing files; use plain
code paths for planned files. Release prerequisites have the explicit temporary
exception recorded in the release policy.

ConfigKit has no owned HTTP service, application CLI, or runtime operations
interface. Do not create those reference documents for consuming applications.

## Boundary rules

Architecture owns governing constraints; ADRs explain why; contracts describe
implemented semantics; internal documentation explains how. A roadmap may link
to all of them but must not become a second current reference.

Release policy owns guarantees; the release procedure owns commands. A release
note cannot redefine a compatibility contract or replace a current-documentation
update. The note at an immutable tag is that release's historical record.

This policy owns what documentation may disclose. Architecture owns security
invariants. Current configuration and Go API contracts own secret-classification
and rendering behavior when implemented; internal docs own their mechanisms.

## Architectural decision records

Use sequential filenames, such as `0001-separate-composition-and-overlay.md`,
and the lightweight Nygard structure: title, status, date, context, decision,
alternatives considered, and consequences.

Accepted decision content is immutable. A changed decision requires a new ADR
and a superseded status/link in the old one. Navigation links may be repaired
when specification ownership moves without rewriting historical rationale.
Rejected architectural alternatives belong in ADRs; deferred or rejected product
features belong in roadmaps. Do not create an ADR for every routine choice.

## Maintenance and verification

Update the owning current documentation in the same change that implements or
changes behavior. When ownership moves, remove the old definition and preserve
useful navigation links.

Before completing documentation work:

- verify claims against the implementation or clearly identify future design;
- check changed local links, paths, fragments, examples, and commands;
- preserve the distinction between policy, decisions, target behavior, and status;
- check canonical ownership and remove stale or duplicate definitions;
- inspect formatting and whitespace;
- ensure no sensitive data was introduced.