166 lines
10 KiB
Markdown
166 lines
10 KiB
Markdown
# Documentation Policy
|
|
|
|
## Purpose
|
|
|
|
This policy assigns each documentation topic to one canonical owner. Its goal is
|
|
to keep this repository's documentation accurate, concise, discoverable, and
|
|
resistant to drift for users, operators, developers, integrators, and LLM
|
|
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
|
|
instead of repeating 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.
|
|
|
|
Minimal tested usage examples are allowed outside the owning contract when this
|
|
policy assigns them an orientation or instructional purpose. They must link to
|
|
the canonical contract and must not redefine complete syntax, defaults, or
|
|
semantics.
|
|
|
|
### Current And Future Behavior
|
|
|
|
Outside `docs/roadmap/`, documentation describes implemented behavior only.
|
|
Partial features may be described only to their implemented boundary.
|
|
|
|
ADRs are the narrow exception: an ADR may record an accepted architectural
|
|
decision before implementation, but acceptance must not be presented as proof
|
|
that the behavior exists. 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.
|
|
|
|
### Audience And Detail
|
|
|
|
Write for the document's stated audience and include only the detail needed for
|
|
its owned topic. User and operator docs should not expose implementation detail.
|
|
Developer docs should link to user-facing and external contracts rather than
|
|
restate them.
|
|
|
|
### 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 instead of embedding a second complete copy.
|
|
|
|
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 end-to-end quickstart | `README.md` | What this project is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. |
|
|
| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, and detailed change recipes, which belong in the relevant internal component document. |
|
|
| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
|
|
| Documentation organization | `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-based sufficiency, test boundaries, doubles, coverage guidance, regression-test 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, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
|
|
| Configuration contract | `docs/config.md` | Application discovery and precedence, source locations, server fields, render default, HTTP limits, and credential mapping. | Promptkit framework formats and defaults, complete example files, CLI syntax, runtime lifecycle, and implementation detail. |
|
|
| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
|
|
| Release procedure | `docs/release.md` | Candidate validation, version and tag operations, hosted-workflow observation, and published-artifact verification. | Runtime operations, version-specific announcements, and complete application-interface contracts. |
|
|
| Version-specific release notes | `docs/releases/` | Immutable release summaries, compatibility notices, and migration announcements for one published version. | Complete CLI, HTTP, configuration, operations, or dependency contracts. |
|
|
| Public HTTP contract | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
|
|
| Consumer guidance | `docs/consumers/` | Choosing between Scriptorium's executable interfaces and understanding consumer responsibilities. | HTTP wire semantics, CLI syntax, Promptkit's Go package, and internal implementation detail. |
|
|
| External and durable integration contracts | `docs/integrations/` | Scriptorium-owned process and executable integration contracts. | Promptkit framework formats and outbound provider protocols, physical runtime placement, internal transformations, CLI syntax, and configuration defaults. |
|
|
| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
|
|
| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
|
|
| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
|
|
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
|
|
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. |
|
|
|
|
Documents that do not exist are required only when the corresponding interface
|
|
or responsibility exists. Do not create placeholder API, consumer, integration,
|
|
or operations documents for behavior the application does not have.
|
|
|
|
## Boundary Rules
|
|
|
|
### Orientation
|
|
|
|
The README owns product orientation. The developer guide routes contributors.
|
|
Architecture owns normative structure. Internal overview owns the current
|
|
concrete component map. These documents may link to one another but should not
|
|
maintain parallel package or behavior descriptions.
|
|
|
|
### Commands, Configuration, And Operations
|
|
|
|
CLI documentation answers how to invoke the application. Configuration
|
|
documentation answers what settings mean. Operations answers what happens to
|
|
runtime state and how to operate or recover the application. When a workflow
|
|
crosses these topics, choose the document that owns the task and link to the
|
|
other contracts.
|
|
|
|
### Contracts And Implementation
|
|
|
|
Integration and API documents define externally observable shapes and
|
|
semantics. Internal documents explain how this project implements or consumes
|
|
those contracts. Internal docs may name a field, file, or protocol to identify
|
|
a dependency, but must link to its canonical contract for the definition.
|
|
|
|
### Security Topics
|
|
|
|
This policy owns what documentation and examples may contain. Architecture owns
|
|
application security invariants. Configuration owns credential-supply
|
|
mechanisms. Operations owns permissions and handling of sensitive runtime
|
|
artifacts. 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.
|
|
|
|
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 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. Its status and
|
|
supersession metadata may be updated, but a changed decision requires a new ADR.
|
|
A superseded ADR must link to its replacement, and the replacement must link
|
|
back to the superseded ADR. Rejected architectural alternatives belong in the
|
|
ADR; rejected product ideas belong in the roadmap.
|
|
|
|
## 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.
|