Lectures

We break down how to write doc comments in Go so that the documentation is genuinely useful: how a comment “binds” to a declaration, why the first line should start with the name ( ParseID, etc.), how to capture the contract and error behavior ( error != nil), how to document types and invariants, and how to use markers like Deprecated: and BUG(who):, as well as how to format paragraphs and mini-examples in GoDoc.

We break down how package documentation works in Go: what a package comment is, why the first sentence becomes the synopsis on pkg.go.dev, why a separate doc.go file is used, what to write in it (purpose, boundaries, API map), and which common mistakes break the “package page” (comment in the wrong place, overly generic wording, mixing documentation and logic).

We break down why README is the interface of your repository and the “first screen” for people: what it must answer (what it is, quick start, examples, code map, constraints), how to make a Quickstart in 60 seconds, how to align the text with the real behavior of the code and avoid overpromising. As an example, we use the educational CLI project Tasky in Go 1.25+ with the structure cmd/tasky and internal/todo, the commands add/ list/ done, and a Mermaid data-flow diagram.

We break down Example‑tests in Go as “living documentation”: where they live ( *_test.go), how they run via go test, how output checking works via // Output:, how Example... names are bound to GoDoc, and how to write examples so they are deterministic and don’t break because of time, map, or someone else’s error text.

We break down how go generate works: the //go:generate directive, explicit generator execution, separating the phases “edit the sources” and “generate code”, and a practical case using stringer to generate the String() method for enum-like constants. Separately, we discuss determinism, committing generated files to the repository, and common organizational mistakes.