Golang Documentation

Go Documentation

Write documentation that helps its intended reader make a correct decision or complete a task. Match the repository's voice, terminology, and existing information architecture.

Establish audience and truth

Before editing:

1. Inspect the documented code, go.mod, existing package comments, examples, README, contribution guidance, and release process.
2. Identify the primary audience: package consumer, CLI user, service operator, contributor, or maintainer.
3. Determine the source of truth for commands, configuration, defaults, compatibility, and generated API material.
4. Check whether the requested change affects a public API, behavior, migration path, or security assumption.

Do not add README, CONTRIBUTING, CHANGELOG, llms.txt, badges, or generated API pages simply because a template exists. Create only artifacts required by the task and repository conventions.

Go package documentation

For exported packages and APIs:

• Describe the contract, purpose, important invariants, side effects, concurrency behavior, ownership, and error conditions that callers cannot infer safely from the signature.
• Keep comments close to the declaration and begin with the declared name when that improves Go documentation and lint compatibility.
• Document units, accepted ranges, zero-value behavior, nil behavior, cancellation, mutation, and resource ownership when relevant.
• State compatibility or deprecation guidance with an actionable replacement and timeline when one exists.
• Avoid repeating the function body line by line or promising implementation details that are not contractual.
• Use package comments to explain the package boundary and the smallest useful usage path.

Examples should be minimal, compilable, deterministic, and safe to copy. Use Go example tests when executable output or discoverability in go doc matters. Do not include live credentials, unstable network dependencies, or time-sensitive output.

Project and application documentation

A useful project entry point normally answers only what the audience needs:

• what the project is and is not;
• how to install or build it using the repository's real commands;
• one verified first-use path;
• configuration precedence and required external services;
• compatibility and support expectations;
• where deeper operational, API, security, and contribution information lives.

For commands, copy help output only when it is generated or kept in sync. For services, document health, startup dependencies, migrations, graceful shutdown, and operator-visible failure modes where applicable.

Keep architecture documentation focused on decisions, boundaries, and consequences. Avoid directory-by-directory prose that becomes stale as soon as files move.

API and change documentation

When behavior changes, update the documentation at the same abstraction level:

• public symbol change: doc comments and examples;
• CLI or configuration change: user guide and migration note;
• service contract change: authoritative API specification and compatibility note;
• operational change: deployment or runbook documentation;
• contributor workflow change: contribution guidance.

A changelog should describe user-visible impact, not restate commit messages. Preserve the project's release format and do not invent semantic-version promises.

Verification

Use the repository's existing checks. Depending on the artifact, verify:

• gofmt and go test for Go examples;
• go doc rendering and package discovery;
• documented commands in a safe local mode;
• local Markdown links and headings;
• names, flags, defaults, environment variables, and output against source;
• generated documentation through its pinned generator rather than hand edits.

Verify examples in a safe local mode. Treat publishing, large site regeneration, and repository-configuration changes as separate deliverables.

Review checklist

• Every statement is supported by current code or an authoritative source.
• The document serves a defined audience and task.
• Examples compile or are clearly marked as illustrative.
• Public contracts include the non-obvious failure and ownership semantics.
• Secrets, personal data, and internal-only endpoints are absent.
• Links are direct, local links resolve, and duplicated guidance has one source of truth.
• Removed or renamed behavior is not still advertised elsewhere.
• The final document is concise enough to stay maintainable.