narratio/docs/documentation/policy.md

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.