ConfigKit/docs/policy/documentation.md

Documentation Policy

Base Policy Version: 1.11

Last Updated: 2026-09-28

Upstream Source: Standard Repository Policies

Purpose

This policy assigns each documentation topic to one canonical owner. Its goal is to keep ConfigKit's documentation accurate, concise, discoverable, and resistant to drift for consumers, maintainers, developers, and 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 for 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.

Architectural constraints may govern future changes. Describe current structure from implemented behavior.

ADRs may record an accepted architectural decision before implementation. 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.

docs/roadmap/deferred.md owns deliberate exclusions; task-specific plans own execution order and progress. Completed plans retire during release preparation.

Audience And Detail

Write for the document's stated audience and include only the detail needed for its owned topic. Keep user and operator docs focused on using and operating the application. Developer docs should link to user-facing and external contracts for their definitions.

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 for complete copyable files.

Executable Go API examples may live beside the relevant package.

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 example	README.md	Purpose, current status, shortest useful Go example, and navigation, including licensing and attribution.	Full Go API and configuration contracts, release procedure, and implementation detail.
Contributor entry point	docs/development.md	Task-oriented reading guide, contributor orientation, baseline validation commands, and canonical links.	Package inventory, architecture rules, subsystem behavior, detailed change recipes.
Application architecture policy	docs/policy/architecture.md	System shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals.	Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work.
Policy-set provenance and upstream navigation	docs/policy/meta.md	Policy-set origin, local authority, adoption baselines, and upstream adoption and update links.	Task-specific reading triggers, detailed adoption procedures, and formal attribution notices.
Agent policy	docs/policy/agents.md	Proportionate, idiomatic implementation; rules against inventing requirements, restrictions, guarantees, or policy.	Application contracts, architecture, testing policy, and contributor procedures.
Documentation policy	docs/policy/documentation.md	Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle.	Application architecture or product behavior.
Testing policy	docs/policy/testing.md	Test philosophy, risk sufficiency, boundaries, doubles, coverage, regressions, and test maintenance.	Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans.
Release policy	docs/policy/release.md	Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks.	Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail.
Open source licensing and attribution policy	docs/policy/oss.md	License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions.	Component entries, license texts, release commands, and dependency security review.
Project copyright and license grant	COPYRIGHT	Project identity, copyright holders and years, SPDX expression, code grant, separately licensed document scope, warranty disclaimer, and third-party statement.	Complete license texts and upstream component attribution.
Project license texts	LICENSE	Complete project and incorporated companion license texts, with required project-specific fields.	General licensing policy and upstream component attribution.
Upstream component attribution	docs/oss/attribution.md	House Format entries for dependencies and adapted documents: identity, material scope, copyright, license, notices, and source links.	General policy, exception reasoning, and complete standard license texts.
Standard license texts	docs/oss/licenses/	Complete, verbatim standard license texts shared by applicable entries, including copied documentation.	Project-specific upstream notices, attribution prose, and policy interpretation.
Repository-specific release procedure	docs/release.md	Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery.	General release requirements, product installation guidance, historical release summaries, and current compatibility contracts.
Exported Go API	Go documentation beside declarations	Symbol contracts, errors, ownership, and lifecycle behavior.	Shared YAML semantics and complete examples.
Configuration contract	docs/config.md	YAML syntax, composition, precedence, schema, defaults, resolution, validation, secrets, and explanation semantics.	Go symbol contracts, complete examples, and implementation detail.
Consumer guidance for the public Go API	docs/consumers/	Task-oriented public Go API usage, minimal examples, and consumer responsibilities.	Go symbol contracts, configuration semantics, and internal implementation detail.
Inventory of implemented internal packages	docs/internal/overview.md	Implemented packages and components, responsibilities, and links to focused internal docs.	Normative architecture, contributor reading policy, external contracts.
Behavior and architecture of internal packages	Other files under docs/internal/	Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests.	Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures.
Architectural decision records	docs/adr/	Significant decisions, context, alternatives, rationale, consequences, and supersession history.	Current behavior reference, implementation status, task sequencing.
Deferred scope	docs/roadmap/deferred.md	Deliberate exclusions and conditions for reconsideration.	Task execution and current behavior.
Future implementation plans	Task-specific files under docs/roadmap/	Unfinished work, sequencing, acceptance, and progress; completed plans retire during release preparation.	Implemented behavior and ADR rationale.
Release-note history	docs/releases/	One checked-in summary per source release under the procedure; the note at its immutable tag is the release record.	Current commands, behavior, contracts, and compatibility definitions.
Complete examples	examples/ and executable Go examples	Maintained copyable artifacts and Go API examples.	Configuration reference, symbol contracts, and prose explanation.

Create supporting documents for existing interfaces and responsibilities when substantive content is available.

Do not create empty owners. Unvalidated candidate and publication work has the temporary exception recorded in the release policy.

Boundary Rules

Orientation

Link among orientation, architecture, and internal documents; maintain each package or behavior description in its canonical owner.

Go API And Configuration

Go declaration documentation owns exported symbol behavior. The configuration contract owns shared YAML and resolution semantics. Consumer guidance explains tasks and links to those contracts.

Releases

The release policy defines requirements and invariants that every release must satisfy. The repository-specific release procedure defines the commands and workflow maintainers use to satisfy that policy. Release notes record history at immutable tags. Maintain current behavior in its canonical documentation, update it with the corresponding behavior changes, and keep release procedures consistent with adopted policy.

Project Licensing And Upstream Attribution

README and release documents link to the canonical licensing and attribution materials under the OSS policy. The release procedure owns URL construction and publication mechanics.

Contracts And Implementation

Go API and configuration documents define externally observable behavior. Internal documents explain implementation and link to the owning contract.

Security Topics

This policy owns what documentation and examples may contain. Architecture owns application security invariants. The configuration and public API contracts own secret-classification, bootstrap, and rendering behavior. 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. Routine choices need no ADR.

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.