Go plans the move from godoc.org to module-aware documentation

A package name is not enough to identify the documentation a dependency user needs. Modules add version information, and a reader must know whether an example or declaration belongs to the version a program actually imports. Moving Go documentation toward a module-aware service addresses that problem. It also creates a migration problem for the links already embedded in source comments, READMEs, and bookmarks.

Today's godoc.org redirect announcement describes the next step toward making pkg.go.dev the primary destination. It does not announce that every request has already moved. Opt-in redirection is available, and the project plans the general redirect after the remaining milestone work is complete. That distinction matters when describing what users can observe today.

I value Go documentation because it helps a reader understand a package before absorbing its implementation. Version context belongs in that process. An accurate explanation of a different version can still lead to an incorrect decision about the dependency in a program.

The path now includes module context

The January account of pkg.go.dev explains the service's purpose. Like godoc.org, it serves package documentation. It also understands modules and provides information about past package versions. That gives the documentation service a model closer to the dependency system used by the Go command.

This changes the question a documentation page answers. A reader is interested in the package at a particular point in its module history, not only in whatever declarations happen to exist now. Package discovery and dependency evaluation consequently need information beyond the package comment itself.

The January plan also identified the confusion caused by maintaining two documentation destinations. Redirecting old links is one way to reduce that confusion while retaining the addressability that users already depend on. The service can change without making every project edit every historical link at once.

The December announcement says requests will redirect to corresponding pages. That promise concerns the meaning of existing links. It is a compatibility requirement for the documentation system, similar in spirit to retaining access to an older interface while changing its implementation. A working destination is more useful than a notice that the old service has moved somewhere else.

The redesign organizes pages around paths

The November redesign gives the migration more concrete context. It organizes the landing page around a path representing a directory in a particular module version. A consistent layout applies regardless of what that directory contains. Readers do not have to infer a different navigation model for each kind of directory.

README placement changes too. The page displays a README at that path when one exists. Previously the overview displayed one only at the module root. A package directory can have explanatory material that is more specific than the top-level module introduction, so this change brings that material into the documentation page where it is relevant.

The documentation section adds an index and a side navigation area. A Jump To input searches identifiers. Those mechanisms address navigation within a package, where a reader may already know the function or type they want. Search for a package and navigation inside its API are different tasks, and the redesigned page provides controls for both.

The page header also carries import and imported-by counts. Banners identify information about the latest minor and major module versions. Those signals help a reader place a package in context, but they do not decide whether it fits an application. A widely imported dependency can still have the wrong semantics for a particular consumer.

I see the version banners as especially useful for preventing an accidental assumption that the page currently open is the only relevant edition of an API. They make module history part of ordinary reading. That is closer to how dependency decisions already work in a module-aware build.

Existing links and machine access have different requirements

The migration announcement distinguishes browser requests from api.godoc.org. It says the transition will not affect that API service, which continues serving traffic until a pkg.go.dev API exists. A browser can follow a new page layout. A program consuming structured responses depends on a separate contract.

Treating those consumers identically would make a website migration into an unannounced API migration. Keeping the API available preserves its current role while replacement access remains a separate project. The announcement links distinct tracking issues for the redirect work and API work, which makes that separation visible to users.

Badges have another compatibility path. Existing badge URLs will redirect to equivalent pkg.go.dev URLs. The announcement also provides a badge generator for projects that want to change their links directly. That avoids requiring every repository to edit its README as a prerequisite to moving the documentation destination.

The gddo repository remains available for users who run their own service or want to fork it. The project plans to archive it and stop accepting contributions. Source availability and ongoing upstream maintenance are different promises. Existing operators can retain the code without assuming the Go team will continue evolving that implementation.

Documentation hosting has its own operational scope

The January discussion already separated the needs of a public documentation service from those of a private organization. An internet-scale implementation can impose complexity that a company does not need merely to browse internal packages. Module support alone does not establish that operating the public service's code is the simplest answer for private documentation.

The December announcement notes that pkgsite is now open source and invites contributions. That makes its implementation available for development and review. It does not erase the earlier operational distinction between public discovery infrastructure and a private documentation deployment.

The immediate user action is optional redirection through the preference offered on godoc.org. The broader transition remains planned work, with existing links and API consumers assigned explicit continuity behavior. Module-aware documentation becomes the intended destination while the migration preserves the routes through which readers and tools already reach it.