Go Documentation: godoc, pkg.go.dev, and the New Wave of AI Tools

Every Go developer has typed godoc somepackage at least once, hit pkg.go.dev for a stranger's library, and recently wondered whether something like DocPilot can keep internal docs alive without a full-time tech writer. The three approaches feel different because they were built for different eras. godoc assumes you're already in a terminal with the source checked out. pkg.go.dev assumes you're evaluating a public dependency. AI documentation tools assume you want the boring parts — READMEs, setup steps, API references — generated, synced, and ignored until something breaks.

Here's how they actually compare in practice.

The Three Generations of Go Documentation

Generation 1: godoc — The Local Power Tool

godoc predates most modern Go developers. It shipped with the language and served two purposes: extract doc comments from your local $GOPATH and serve them as HTML. The CLI mode (godoc fmt) is gone in favor of go doc, but the older binary still exists in the toolchain for those who want it.

The modern invocation looks like this:

go doc net/http.Server
go doc -all encoding/json
go doc -short -src sync.WaitGroup

What you get back is plain-text prose with function signatures, pulled straight from the source tree. No network. No build step. No opinions.

Strengths

• Zero setup. If you have the Go toolchain, you have this.
• Works offline against any module in your cache.
• Renders correctly because it's reading the same source you are.
• The -src flag is underrated — it shows the actual implementation right under the declaration.

Limitations

• No cross-referencing between packages unless you crawl them manually.
• Output is monochrome plain text. Fine for a terminal, painful for sharing.
• Doesn't help you write documentation — it only surfaces what's already there.
• No versioning awareness. You're looking at whatever's in your module cache.

For a senior developer debugging an obscure net/http behavior, go doc is still the fastest path from question to answer. It won't help you write a README, but it was never trying to.

Generation 2: pkg.go.dev — The Public Discovery Layer

The Go team launched pkg.go.dev in 2020 to replace godoc.org. It's the official index of every public module, scraped from the module proxy, and rebuilt into something closer to a search engine than a help viewer.

Where godoc was a flashlight, pkg.go.dev is a library catalog. You can land on it from a search engine, browse by package, inspect a specific version, and see popularity metrics. The "Popularity" score uses a blend of download counts and dependents, the "Package coverage" bar shows how much of the API has doc comments, and the "Dependencies" section helps you reason about blast radius before pulling something in.

Strengths

• Universal access. Any published module gets indexed automatically.
• Version pinning. You can read the docs for v1.4.2 vs v2.0.0 separately.
• Quality signals. Coverage and popularity help you triage unknowns.
• Cross-package links resolve cleanly, including to standard library.
• The "Open in Playground" and "Open in VS Code" buttons are quietly useful.

Limitations

• Only public modules. Your internal github.com/acme/secret-payments service is invisible.
• No editing controls. You're a reader, not a writer.
• Re-indexing latency can be annoying — push a doc fix and you might wait minutes.
• Doesn't generate anything. If your package has thin docs, pkg.go.dev shows that with brutal clarity.

For evaluating third-party libraries, pkg.go.dev is the default and rightly so. For your own services, it's irrelevant — and that's the gap AI tools are trying to fill.

Generation 3: AI Documentation Generators

The newest category covers tools that ingest a repository and produce human-readable documentation from the code itself. DocPilot sits in this group, alongside a handful of others like Mintlify, ReadMe, and various IDE plugins. The pitch is consistent: connect your GitHub repo, get a README, an architecture overview, an API reference, and a setup guide, and keep it all in sync when code changes.

For Go specifically, the interesting question is whether AI tools add value beyond what go doc already gives you.

The answer is yes — but only for the right job. AI tools don't replace godoc for API ergonomics questions. They replace the documentation debt that accumulates in private repos.

What Each Tool Does Best

A simple matrix:

Task	godoc / go doc	pkg.go.dev	AI tools (DocPilot, etc.)
Reading standard library docs	Excellent	Excellent	Redundant
Reading third-party public libs	Good (if cached)	Best in class	Redundant
Generating a README from scratch	None	None	Core feature
Keeping docs in sync with code	None	Lagged	Webhook-driven
Documenting internal/private modules	Local only	Not indexed	Core feature
API reference generation	Manual	Manual	Automated
Setup/onboarding guides	None	None	Core feature
Architecture diagrams	None	None	Some tools offer this
Evaluating unknown deps	Workable	Purpose-built	Overkill

The columns don't really overlap. They serve different parts of the documentation lifecycle.

Real Workflow: How the Three Compose

Here's a typical flow for a Go engineer at a mid-size startup.

Step 1 — Evaluating a new dependency.

You need a Postgres connection pooler. You search, land on pgx's pkg.go.dev page, scan the coverage bar, check the version, and read the README rendered there. pkg.go.dev wins.

Step 2 — Implementing against it.

You're in your editor and need the exact signature for pgxpool.Pool.Acquire. You run go doc github.com/jackc/pgx/v5/pgxpool.Pool.Acquire and get the answer in under a second. godoc wins.

Step 3 — Documenting the service you just shipped.

You open a PR and realize the README still says "coming soon" under the Setup section. You wire DocPilot to your repo, point it at the cmd/ and internal/ packages, and let it generate setup instructions, environment variables, and the API reference. It commits via a webhook and opens a PR. AI tools win.

These three steps would be miserable if you tried to do them with one tool. The ecosystem only works because the tools stayed in their lane.

Where AI Documentation Tools Struggle with Go

Honest assessment: AI-generated Go docs aren't perfect, and a few failure modes show up repeatedly.

1. Goroutine and channel semantics are hard to summarize.

A function that launches goroutines, closes channels in defer, and uses context.Done() reads cleanly in go doc -src but gets summarized by AI as "this function handles async operations." That's worse than nothing — it's confidently vague.

2. Interface satisfaction is implicit.

Go's interfaces are satisfied structurally, which means AI tools often miss that a concrete type implements io.Reader until they trace every method by hand. The output then references methods that don't exist.

3. Build tags and platform conditionals.

//go:build linux

package platform

A generator that doesn't respect build tags will document Windows-only code as if it runs on Linux. The best tools now parse go build output rather than just walking the AST.

4. Generated code.

Anything from go generate, protobuf output, or templated files will get documented as if a human wrote it. The fix is excluding these paths in the tool's config.

If you pick a tool that handles these correctly — and most of the better ones do — the output is good enough to ship after a human review pass. The cost saving isn't zero human time; it's removing the blank-page problem.

A Pragmatic Setup for Go Teams

If I were standing up a documentation stack today, here's what I'd do.

1. Standardize doc comments on every exported identifier. Enforce with golint or revive in CI. This makes every downstream tool — go doc, pkg.go.dev, and AI generators — produce better output.
2. Pin pkg.go.dev as the public face for any open-source module your team publishes.
3. Wire an AI documentation tool to private repos via a GitHub App and webhook. Let it open PRs into a docs/ folder or branch. Review, don't block.
4. Keep go doc in muscle memory for the daily "what does this function do" questions. Nothing else is faster.

The reason this stack works is that each tool handles a different cost. godoc removes friction from looking. pkg.go.dev removes friction from evaluating. AI tools remove friction from writing.

The Real Comparison

The framing "AI tools vs godoc" misses the point. They're not competing for the same job. godoc is a reader for source code. pkg.go.dev is an index for published modules. AI tools are writers for private repositories. Each is the best tool in its category, and the smartest teams run all three.

If you've only ever used godoc, the leap to pkg.go.dev will feel like a productivity gain on its own. If you've never used an AI documentation tool, the leap is bigger — but only for the boring parts of the job, which is exactly the point. The fun parts of writing good docs (deciding what to document, drawing the architecture, capturing the why) still belong to humans. The tedious parts (syncing README sections to match code changes, regenerating API tables after a refactor, keeping setup instructions honest) are exactly what these tools exist to take off your plate.

---

DocPilot fits into this stack the same way godoc and pkg.go.dev do, just for the missing layer: internal Go services whose docs would otherwise drift. Connect a repo, let it generate the README, setup guide, and API reference from your actual code, and let the webhook keep everything in sync when you push. If your team has more Go services than tech writers, it's worth a look — try DocPilot free and see what it pulls out of your repo.