golang-documentation

$27

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

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

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 (via the Agent tool) 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:

// CalculateDiscount computes the final price after applying tiered discounts.

// Discounts are applied progressively based on order quantity: each tier unlocks

// additional percentage reduction. Returns an error if the quantity is invalid or

// if the base price would result in a negative value after discount application.

//

// Parameters:

//   - basePrice: The original price before any discounts (must be non-negative)

//   - quantity: The number of units ordered (must be positive)

//   - tiers: A slice of discount tiers sorted by minimum quantity threshold

//

// Returns the final discounted price rounded to 2 decimal places.

// Returns ErrInvalidPrice if basePrice is negative.

// Returns ErrInvalidQuantity if quantity is zero or negative.

//

// Play: https://go.dev/play/p/abc123XYZ

//

// Example:

//

//	tiers := []DiscountTier{

//	    {MinQuantity: 10, PercentOff: 5},

//	    {MinQuantity: 50, PercentOff: 15},

//	    {MinQuantity: 100, PercentOff: 25},

//	}

//	finalPrice, err := CalculateDiscount(100.00, 75, tiers)

//	if err != nil {

//	    log.Fatalf("Discount calculation failed: %v", err)

//	}

//	log.Printf("Ordered 75 units at $100 each: final price = $%.2f", finalPrice)

func CalculateDiscount(basePrice float64, quantity int, tiers []DiscountTier) (float64, error) {

    // implementation

}

For the full comment format, deprecated markers, interface docs, and file-level comments, see Code Comments — 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:

• Title — project name as # heading

• Badges — shields.io pictograms (Go version, license, CI, coverage, Go Report Card...)

• Summary — 1-2 sentences explaining what the project does

• Demo — code snippet, GIF, screenshot, or video showing the project in action

• Getting Started — installation + minimal working example

• Features / Specification — detailed feature list or specification (very long section)

• Contributing — link to CONTRIBUTING.md or inline if very short

• Contributors — thank contributors (badge or list)

• License — license name + link

Common badges for Go projects:

[![Go Version](https://img.shields.io/github/go-mod/go-version/{owner}/{repo})](https://go.dev/) [![License](https://img.shields.io/github/license/{owner}/{repo})](./LICENSE) [![Build Status](https://img.shields.io/github/actions/workflow/status/{owner}/{repo}/test.yml?branch=main)](https://github.com/{owner}/{repo}/actions) [![Coverage](https://img.shields.io/codecov/c/github/{owner}/{repo})](https://codecov.io/gh/{owner}/{repo}) [![Go Report Card](https://goreportcard.com/badge/github.com/{owner}/{repo})](https://goreportcard.com/report/github.com/{owner}/{repo}) [![Go Reference](https://pkg.go.dev/badge/github.com/{owner}/{repo}.svg)](https://pkg.go.dev/github.com/{owner}/{repo})

For the full README guidance and application-specific sections, see Project Docs.

Step 5: CONTRIBUTING & Changelog

CONTRIBUTING.md — Help contributors get started in under 10 minutes. Include: prerequisites, clone, build, test, PR process. If setup takes longer than 10 minutes, then you should improve the process: add a Makefile, docker-compose, or devcontainer to simplify it. See Project Docs.

Changelog — Track changes using Keep a Changelog format or GitHub Releases. Copy the template from templates/CHANGELOG.md. See Project Docs.

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 the go-playground MCP tool when 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. Use go doc locally to preview.

• 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 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 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 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. 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:

go get github.com/{owner}/{repo}

Applications:

# Pre-built binary

curl -sSL https://github.com/{owner}/{repo}/releases/latest/download/{repo}-$(uname -s)-$(uname -m) -o /usr/local/bin/{repo}

# From source

go install github.com/{owner}/{repo}@latest

# Docker

docker pull {registry}/{owner}/{repo}:latest

See Project Docs for Dockerfile best practices and Homebrew tap setup.