397 lines
11 KiB
Markdown
397 lines
11 KiB
Markdown
# Go Project Documentation Policy
|
||
|
||
## Purpose
|
||
|
||
Project documentation must help five audiences:
|
||
|
||
1. users who need to run the application;
|
||
2. administrators/operators who need to configure and operate it;
|
||
3. developers who need to understand and change it safely;
|
||
4. LLM coding agents that need clear scope, boundaries, and invariants;
|
||
5. developers and LLM coding agents integrating this project from another codebase.
|
||
|
||
Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
|
||
|
||
## Core Rules
|
||
|
||
### 1. Keep docs concise
|
||
|
||
Each document should cover a defined scope and only the essentials for that scope.
|
||
|
||
Avoid:
|
||
- long background explanations;
|
||
- repeated reference material;
|
||
- implementation detail in user-facing docs;
|
||
- aspirational language outside roadmap docs;
|
||
- verbose examples where one minimal example is clearer.
|
||
|
||
### 2. Document only implemented behavior outside roadmap files
|
||
|
||
Unimplemented, planned, aspirational, experimental, or future work may be described only under:
|
||
|
||
- `docs/roadmap/`
|
||
|
||
No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
|
||
|
||
If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
|
||
|
||
### 3. Use canonical homes
|
||
|
||
Each type of information should have one canonical location.
|
||
|
||
Canonical homes:
|
||
|
||
- project purpose and quickstart: `README.md`
|
||
- development principles: `docs/policy/architecture.md`
|
||
- configuration reference: `docs/config.md`
|
||
- CLI reference: `docs/cli.md`
|
||
- operations and recovery: `docs/operations.md`
|
||
- troubleshooting: `docs/troubleshooting.md`
|
||
- public API/package consumer guidance: `docs/consumers/`
|
||
- implemented internals: `docs/internal/`
|
||
- external protocol, service, and file-format contracts: `docs/integrations/`
|
||
- future work: `docs/roadmap/`
|
||
- contributor workflow: `docs/policy/development.md`
|
||
- copyable examples: `examples/`
|
||
|
||
Other files should summarize briefly and link to the canonical source.
|
||
|
||
### 4. Keep examples real
|
||
|
||
Examples should be valid, maintained, and free of secrets.
|
||
|
||
Where practical:
|
||
- example configs should load successfully;
|
||
- example commands should match real CLI syntax;
|
||
- important examples should be covered by tests.
|
||
|
||
## Documentation Profiles
|
||
|
||
All projects require:
|
||
|
||
- `README.md`
|
||
- `docs/policy/architecture.md`
|
||
|
||
Additional docs depend on the project.
|
||
|
||
### Small library
|
||
|
||
Recommended:
|
||
- `docs/policy/development.md`, if contributor conventions are non-obvious
|
||
|
||
### Simple CLI
|
||
|
||
Required:
|
||
- `docs/cli.md`
|
||
|
||
Recommended:
|
||
- `docs/policy/development.md`
|
||
|
||
### Config-driven CLI
|
||
|
||
Required:
|
||
- `docs/cli.md`
|
||
- `docs/config.md`
|
||
|
||
Recommended:
|
||
- `examples/`
|
||
- `docs/policy/development.md`
|
||
|
||
### Stateful or operator-facing application
|
||
|
||
Required:
|
||
- `docs/cli.md`, if CLI-based
|
||
- `docs/config.md`, if config-driven
|
||
- `docs/operations.md`
|
||
|
||
Recommended:
|
||
- `docs/troubleshooting.md`
|
||
- `examples/`
|
||
- `docs/policy/development.md`
|
||
|
||
### Modular, service-oriented, or orchestration application
|
||
|
||
Required:
|
||
- `docs/cli.md`, if CLI-based
|
||
- `docs/config.md`, if config-driven
|
||
- `docs/operations.md`
|
||
- `docs/internal/`
|
||
- `docs/policy/development.md`
|
||
|
||
Recommended:
|
||
- `docs/troubleshooting.md`
|
||
- validated examples under `examples/`
|
||
|
||
### Project with public packages or consumer APIs
|
||
|
||
Required:
|
||
- `docs/consumers/api.md`
|
||
- one `docs/consumers/pkg-<name>.md` file per public package, if public packages exist
|
||
|
||
Recommended:
|
||
- copyable consumer examples under `examples/`, if practical
|
||
|
||
## Required Documents
|
||
|
||
### README.md
|
||
|
||
**Audience:** users, administrators, operators
|
||
|
||
The README is the outward-facing project orientation page.
|
||
|
||
It should include, in order:
|
||
|
||
1. concise description;
|
||
2. elevator pitch;
|
||
3. shortest useful command or usage example;
|
||
4. links to targeted docs.
|
||
|
||
The README should be short. It is not a manual.
|
||
|
||
The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
|
||
|
||
### docs/policy/architecture.md
|
||
|
||
**Audience:** developers, LLM coding agents
|
||
|
||
`docs/policy/architecture.md` is required for every project.
|
||
|
||
It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
|
||
|
||
It should include:
|
||
|
||
- project shape;
|
||
- core design principles;
|
||
- package and boundary philosophy;
|
||
- state/persistence philosophy, if applicable;
|
||
- external integration philosophy, if applicable;
|
||
- error-handling and logging principles;
|
||
- testing expectations;
|
||
- documentation expectations;
|
||
- architectural invariants;
|
||
- explicit non-goals, if useful.
|
||
|
||
For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
|
||
|
||
### docs/policy/development.md
|
||
|
||
**Audience:** developers, LLM coding agents
|
||
|
||
Required for projects maintained by humans and LLM coding agents.
|
||
|
||
It should include:
|
||
|
||
- repository layout;
|
||
- build/test commands;
|
||
- coding conventions;
|
||
- dependency policy;
|
||
- how to add config fields;
|
||
- how to add CLI flags;
|
||
- how to add modules or adapters, if applicable;
|
||
- how to update examples;
|
||
- documentation update expectations.
|
||
|
||
### docs/config.md
|
||
|
||
**Audience:** administrators, operators, advanced users
|
||
|
||
Required for applications with configuration files.
|
||
|
||
It should include, in order:
|
||
|
||
1. config file locations and discovery precedence;
|
||
2. minimal working config;
|
||
3. production-oriented config;
|
||
4. full configuration reference;
|
||
5. secrets handling, if applicable;
|
||
6. links to maintained examples.
|
||
|
||
The full configuration reference should be canonical.
|
||
|
||
### docs/cli.md
|
||
|
||
**Audience:** users, administrators, operators
|
||
|
||
Required for CLI applications.
|
||
|
||
It should include, in order:
|
||
|
||
1. shortest useful command;
|
||
2. command overview;
|
||
3. complete flag reference;
|
||
4. common workflows;
|
||
5. diagnostic or recovery commands, if applicable.
|
||
|
||
Explain when commands are useful, not just their syntax.
|
||
|
||
### docs/operations.md
|
||
|
||
**Audience:** administrators, operators
|
||
|
||
Required for applications that maintain state, support resume behavior, run multi-step workflows, write durable artifacts, use remote storage, or require recovery procedures.
|
||
|
||
It should cover:
|
||
|
||
- normal workflow;
|
||
- filesystem layout;
|
||
- remote storage layout, if applicable;
|
||
- logs and manifests;
|
||
- resume/retry behavior;
|
||
- cleanup behavior;
|
||
- archive/backup behavior;
|
||
- safe recovery procedures;
|
||
- operational caveats.
|
||
|
||
### docs/troubleshooting.md
|
||
|
||
**Audience:** administrators, operators
|
||
|
||
Recommended once recurring failure modes exist.
|
||
|
||
Each entry should include:
|
||
|
||
- symptom;
|
||
- likely cause;
|
||
- diagnostic command or inspection step;
|
||
- safe fix;
|
||
- relevant links.
|
||
|
||
### docs/consumers/
|
||
|
||
**Audience:** developers and LLM coding agents integrating this project from another codebase
|
||
|
||
Required for projects with public packages, SDKs, client APIs, plugin APIs, or other application-facing integration surfaces.
|
||
|
||
This directory describes how an external codebase should consume the project's public API. It should be task-oriented and copyable where useful. It is not the place for internal implementation details or operator procedures.
|
||
|
||
`docs/consumers/api.md` should provide the consumer-facing overview and primary implementation workflow. It should include:
|
||
|
||
1. intended consumer audience and use cases;
|
||
2. required inputs supplied by operators or deployment configuration;
|
||
3. recommended public package or API workflow;
|
||
4. minimal copyable example;
|
||
5. consumer responsibilities and boundaries;
|
||
6. retry, idempotency, or status behavior, if applicable;
|
||
7. links to package-specific docs and canonical integration contracts.
|
||
|
||
Package-specific docs should be named `pkg-<name>.md` and should include:
|
||
|
||
1. import path;
|
||
2. intended use cases;
|
||
3. primary types and functions needed by consumers;
|
||
4. minimal examples;
|
||
5. validation, error, retry, and boundary behavior;
|
||
6. links to canonical file-format or wire-protocol contracts.
|
||
|
||
### docs/internal/
|
||
|
||
**Audience:** developers, LLM coding agents
|
||
|
||
Required for modular, service-oriented, or orchestration projects.
|
||
|
||
This directory describes implemented internal components. It is not the roadmap.
|
||
|
||
Use one file per major component where useful.
|
||
|
||
Each component doc should include:
|
||
|
||
1. purpose;
|
||
2. inputs and outputs;
|
||
3. boundaries;
|
||
4. config fields used;
|
||
5. external adapters used;
|
||
6. state or manifest behavior, if applicable;
|
||
7. skip/resume behavior, if applicable;
|
||
8. failure behavior;
|
||
9. tests to inspect before changing;
|
||
10. architectural invariants.
|
||
|
||
### docs/roadmap/
|
||
|
||
**Audience:** maintainers, developers, LLM coding agents
|
||
|
||
This is the only place for planned, future, aspirational, experimental, or unimplemented work.
|
||
|
||
Roadmap docs should clearly distinguish:
|
||
|
||
- proposed work;
|
||
- accepted plans;
|
||
- deferred ideas;
|
||
- rejected ideas;
|
||
- implementation prompts or task breakdowns, if useful.
|
||
|
||
Roadmap docs should not be confused with current behavior.
|
||
|
||
### docs/integrations/
|
||
|
||
**Audience:** developers, LLM coding agents
|
||
|
||
Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
|
||
|
||
This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses or exposes.
|
||
|
||
Use one file per integration where useful.
|
||
|
||
## Examples Directory
|
||
|
||
Projects with non-trivial configuration or workflows should include `examples/`.
|
||
|
||
Useful examples include:
|
||
|
||
- minimal working config;
|
||
- production-oriented config;
|
||
- full annotated config;
|
||
- local development config;
|
||
- remote/object-storage config;
|
||
- minimal session/input file.
|
||
|
||
Examples should be valid, maintained, tested when practical, and linked from relevant docs.
|
||
|
||
## Security and Privacy
|
||
|
||
Docs and examples must not include:
|
||
|
||
- real API keys;
|
||
- tokens;
|
||
- passwords;
|
||
- private keys;
|
||
- private environment dumps;
|
||
- sensitive user data;
|
||
- raw private transcripts;
|
||
- private infrastructure details unless intentionally public.
|
||
|
||
Document secret-handling mechanisms, not actual secret values.
|
||
|
||
## Maintenance Rules
|
||
|
||
When docs change, verify the affected behavior.
|
||
|
||
Where practical:
|
||
|
||
- load example config files in tests;
|
||
- test CLI examples or command parser behavior;
|
||
- validate documented flags against real flags;
|
||
- remove stale references;
|
||
- update links after renames;
|
||
- keep roadmap content out of non-roadmap docs.
|
||
|
||
If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
|
||
|
||
Documentation is complete only when it matches the current code.
|
||
|
||
## Documentation Change Checklist
|
||
|
||
Before merging documentation changes, verify:
|
||
|
||
- README is concise and orientation-focused.
|
||
- `docs/policy/architecture.md` describes development principles.
|
||
- Future work appears only under `docs/roadmap/`.
|
||
- User-facing docs avoid unnecessary internals.
|
||
- Consumer-facing docs explain public APIs without duplicating integration contracts.
|
||
- Developer-facing docs preserve boundaries and invariants.
|
||
- Config examples match the schema.
|
||
- CLI examples match real commands and flags.
|
||
- Defaults appear in the canonical config reference.
|
||
- No secrets or private data are included.
|
||
- Links are accurate.
|