notarius/docs/policy/documentation.md

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
• public HTTP API reference: docs/api.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/

Public HTTP API service

Required:

• docs/api.md
• 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
• docs/consumers/, for task-oriented client integration guides
• docs/integrations/, for upstream/downstream service contracts
• 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/api.md

Audience: external HTTP API consumers, developers, LLM coding agents integrating by HTTP

Required for projects whose primary public interface is HTTP.

docs/api.md is the canonical public HTTP API contract. It should be normative for external consumers and should not be duplicated by README, operations docs, consumer guides, or integration docs.

It should include:

1. base URL conventions;
2. authentication and authorization behavior, if implemented;
3. response envelope;
4. supported media types and content negotiation behavior;
5. shared query parameters;
6. endpoint reference grouped by route family;
7. request parameters and validation rules;
8. response fields, units, nullability, and optionality;
9. error response shape and status codes;
10. pagination, caching, rate-limit, idempotency, and retry behavior, if implemented;
11. compact request and response examples.

It must document only implemented endpoints and behavior. Planned endpoints, proposed fields, future filters, and experimental response shapes belong only under docs/roadmap/.

For HTTP API projects, docs/consumers/ may provide task-oriented client integration guides, but those guides should link to docs/api.md for the authoritative endpoint contract.

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.

For projects whose public API is HTTP, docs/consumers/ is not required, and it should not duplicate the endpoint reference in docs/api.md. If present, it may provide practical integration workflows, client-specific examples, or migration notes that link back to docs/api.md.

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.

For public HTTP API services, docs/integrations/ should document upstream, downstream, storage, protocol, or runtime contracts that the service depends on or bridges. It should not become a second copy of the public HTTP endpoint reference; that belongs in docs/api.md.

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.
• docs/api.md is the canonical HTTP contract for HTTP API services.
• Future work appears only under docs/roadmap/.
• User-facing docs avoid unnecessary internals.
• Consumer-facing docs explain public APIs without duplicating HTTP endpoint or 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.