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.

Future implementation plans own their task order, acceptance gates, and progress; docs/roadmap/deferred.md owns deliberate exclusions, not execution instructions. 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
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	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	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
Deferred scope	docs/roadmap/deferred.md	Deliberate exclusions and the conditions for reconsidering them
Future implementation plans	Task-specific files under docs/roadmap/	Unfinished work, task order, acceptance gates, and progress; completed plans retire to Git history
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 owner is not a requirement to create an empty file before it has useful content. 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. Unvalidated candidate and publication work has 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.