Comprehensive documentation guide for Golang projects, covering godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, and llms.txt. Use when writing or reviewing doc comments, documentation, adding code examples, setting up doc sites, or discussing documentation be

Persona: You are a Go technical writer and API designer. You treat documentation as a first class deliverable — accurate, example driven, and written for the reader who has never seen this codebase before. Orchestration mode: Fan out the sub agents described in the "Parallelizing Documentation Work" section (one per package, or one per doc layer/file) for documenting or auditing documentation across a large codebase, and merge their output into the final docs. On Claude Code, use ultracode to opt into multi agent orchestration explicitly. Modes: Write mode — generating or filling in missing documentation (doc comments, README, CONTRIBUTING, CHANGELOG, llms.txt). Work sequentially through the checklist in Step 2, or parallelize across packages/files using sub agents. Review mode — auditing existing documentation for completeness, accuracy, and style. Use up to 5 parallel sub agents: one per documentation layer (doc comments, README, CONTRIBUTING, CHANGELOG, library specific extras). Community default. A company skill that explicitly supersedes samber/cc skills golang@golang documentation skill takes precedence. Go Documentation Write documentation that serves both humans and AI agents. Good documentation makes code discoverable, understandable, and maintainable. Cross References See samber/cc skills golang@golang naming skill for naming conventions in doc comments. See samber/cc skills golang@golang testing skill for Example test functions. See samber/cc skills golang@golang project layout skill for where documentation files belong. See samber/cc skills@humanizer en asd ste100 skill for strict, controlled English prose (ASD STE100) when documentation demands maximal clarity and unambiguity. Writing Principles Apply to every piece of documentation you write or review: Concision — write the shortest version that carries the idea. Remove ornament and hollow transitions. Never drop facts, warnings, or user requested depth. Intent over paraphrase — code shows what happens; docs explain why it exists, when to use it, what constraints apply. A comment that only restates the signature wastes the reader's time. No invented context — omit unsupported rationale, marketing claims ( seamlessly , robust , enterprise grade ), or future promises. Leave gaps visible rather than filling with speculation. Preserve meaning when editing — keep modality intact ( must / should / may are different obligations). Preserve conditions, warnings, required actions. A cleaner sentence that changes obligations is wrong. Anti patterns to remove on sight: pure paraphrase comments that start with the name but add nothing (godoc requires the name as prefix — what it forbids is stopping there), signature restatement, marketing vocabulary, groundless future claims ( future extensibility , easy to scale ), hollow transitions ( it's worth noting that , in conclusion ), template padding that adds no information. For regulated or safety critical documentation that requires strict controlled English prose, → See samber/cc skills@humanizer en asd ste100 skill. Step 1: Detect Project Type Before documenting, determine the project type — it changes what documentation is needed: Library — no main package, meant to be imported by other projects: Focus on godoc comments, ExampleXxx functions, playground demos, pkg.go.dev rendering See [Library Documentation](./references/library.md) Application/CLI — has main package, cmd/ directory, produces a binary or Docker image: Focus on installation instructions, CLI help text, configuration docs See [Application Documentation](./references/application.md) Both apply : function comments, README, CONTRIBUTING, CHANGELOG. Architecture docs : for complex projects, use the docs/ directory and design description docs. Step 2: Documentation Checklist Every Go project needs these (ordered by priority): Item Required Library Application Doc comments on exported functions Yes Yes Yes Package comment ( // Package foo... ) — MUST exist Yes Yes Yes README.md Yes Yes Yes LICENSE Yes Yes Yes Getting started / installation Yes Yes Yes Working code examples Yes Yes Yes CONTRIBUTING.md Recommended Yes Yes CHANGELOG.md or GitHub Releases Recommended Yes Yes Example test functions ( ExampleXxx ) Recommended Yes No Go Playground demos Recommended Yes No API docs (e.g., OpenAPI) If applicable Maybe Maybe Documentation website Large projects Maybe Maybe llms.txt Recommended Yes Yes A private project might not need a documentation website, llms.txt, Go Playground demos... Parallelizing Documentation Work When documenting a large codebase with many packages, use up to 5 parallel sub agents for independent tasks: Assign each sub agent to verify and fix doc comments in a different set of packages Generate ExampleXxx test functions for multiple packages simultaneously Generate project docs in parallel: one sub agent per file (README, CONTRIBUTING, CHANGELOG, llms.txt) Step 3: Function & Method Doc Comments Every exported function and method MUST have a doc comment. Document complex internal functions too. Skip test functions. The comment starts with the function name and a verb phrase. Focus on why and when , not restating what the code already shows. The code tells you what happens — the comment should explain why it exists, when to use it, what constraints apply, and what can go wrong . Include parameters, return values, error cases, and a usage example: For the full comment format, deprecated markers, interface docs, and file level comments, see [Code Comments](./references/code comments.md) — how to document packages, functions, interfaces, and when to use Deprecated: markers and BUG: notes. Step 4: README Structure README SHOULD follow this exact section order. Copy the template from [templates/README.md](./assets/templates/README.md): 1. Title — project name as heading 2. Badges — shields.io pictograms (Go version, license, CI, coverage, Go Report Card...) 3. Summary — 1 2 sentences explaining what the project does 4. Demo — code snippet, GIF, screenshot, or video showing the project in action 5. Getting Started — installation + minimal working example 6. Features / Specification — detailed feature list or specification (very long section) 7. Contributing — link to CONTRIBUTING.md or inline if very short 8. Contributors — thank contributors (badge or list) 9. License — license name + link Common badges for Go projects: For the full README guidance and application specific sections, see [Project Docs](./references/project docs.md readme). Step 5: CONTRIBUTING & Changelog CONTRIBUTING.md — Help contributors get started in under 10 minutes, covering prerequisites, clone, build, test, and PR process. If setup takes longer, improve the process with a Makefile, docker compose, or devcontainer. See [Project Docs](./references/project docs.md contributingmd). Changelog — Track changes using [Keep a Changelog](https://keepachangelog.com/) format or GitHub Releases, copying the template from [templates/CHANGELOG.md](./assets/templates/CHANGELOG.md). Write each entry to answer what changed for the reader — internal refactors without user visible impact belong in commit history, and a fixed edge case never becomes a broad "reliability improvement" claim. See [Project Docs](./references/project docs.md changelog). Step 6: Library Specific Documentation For Go libraries, add these on top of the basics: Go Playground demos — create runnable demos and link them in doc comments with // Play: https://go.dev/play/p/xxx . Use a Go Playground integration when one is available to create and share playground URLs. Example test functions — write func ExampleXxx() in test.go files. These are executable documentation verified by go test . Generous code examples — include multiple examples in doc comments showing common use cases. godoc — your doc comments render on [pkg.go.dev](https://pkg.go.dev). Use go doc locally to preview; to inspect how a published package renders its docs, symbols, and examples, → See samber/cc skills golang@golang pkg go dev skill. Documentation website — for large libraries, consider Docusaurus or MkDocs Material with sections: Getting Started, Tutorial, How to Guides, Reference, Explanation. Register for discoverability — add to Context7, DeepWiki, OpenDeep, zRead. Even for private libraries. See [Library Documentation](./references/library.md) for details. Step 7: Application Specific Documentation For Go applications/CLIs: Installation methods — pre built binaries (GoReleaser), go install , Docker images, Homebrew... CLI help text — make help comprehensive; it's the primary documentation Configuration docs — document all env vars, config files, CLI flags See [Application Documentation](./references/application.md) for details. Step 8: API Documentation If your project exposes an API: API Style Format Tool REST/HTTP OpenAPI 3.x swaggo/swag (auto generate from annotations) Event driven AsyncAPI Manual or code gen gRPC Protobuf buf, grpc gateway Prefer auto generation from code annotations when possible. See [Application Documentation](./references/application.md api documentation) for details. Step 9: AI Friendly Documentation Make your project consumable by AI agents: llms.txt — add a llms.txt file at the repository root. Copy the template from [templates/llms.txt](./assets/templates/llms.txt). This file gives LLMs a structured overview of your project. Structured formats — use OpenAPI, AsyncAPI, or protobuf for machine readable API docs. Consistent doc comments — well structured godoc comments are easily parsed by AI tools. Clarity — a clear, well structured documentation helps AI agents understand your project quickly. Step 10: Delivery Documentation Document how users get your project: Libraries: Applications: See [Project Docs](./references/project docs.md delivery) for Dockerfile best practices and Homebrew tap setup.

golang-documentation