# Go Project Documentation Policy

## Purpose

Project documentation must help four 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.

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/architecture.md`
- configuration reference: `docs/config.md`
- CLI reference: `docs/cli.md`
- operations and recovery: `docs/operations.md`
- troubleshooting: `docs/troubleshooting.md`
- implemented internals: `docs/internal/`
- future work: `docs/roadmap/`
- contributor workflow: `docs/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/architecture.md`

Additional docs depend on the project.

### Small library

Recommended:
- `docs/development.md`, if contributor conventions are non-obvious

### Simple CLI

Required:
- `docs/cli.md`

Recommended:
- `docs/development.md`

### Config-driven CLI

Required:
- `docs/cli.md`
- `docs/config.md`

Recommended:
- `examples/`
- `docs/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/development.md`

### Modular, staged, service-oriented, or orchestration application

Required:
- `docs/cli.md`, if CLI-based
- `docs/config.md`, if config-driven
- `docs/operations.md`
- `docs/internal/`
- `docs/development.md`

Recommended:
- `docs/troubleshooting.md`
- validated examples under `examples/`

## 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/architecture.md

**Audience:** developers, LLM coding agents

`docs/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/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 multiple stages, 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/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 stages/modules/adapters, if applicable;
- how to update examples;
- documentation update expectations.

### docs/internal/

**Audience:** developers, LLM coding agents

Required for modular, staged, 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.

## 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/architecture.md` describes development principles.
- Future work appears only under `docs/roadmap/`.
- User-facing docs avoid unnecessary internals.
- 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.