Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
proposal: doc: restructure module documentation #33637
Go module documentation is spread out over several sources. The canonical source is
This issue proposes restructuring module documentation into three main areas.
A complete reference for everything related to modules should be added as one or more structured documents linked from golang.org/doc under the References section. This is analogous to the Language specification or The Go memory model.
The specification should be written as HTML documents within the main Go repository. Updates on the website will be tied to the Go release cycle. This is desirable since things like the go.mod format and the proxy protocol are tied to the current release. The latest version of the documentation will always be visible from tip.golang.org.
The specification should include the following sections. Note that this is simply a rough list of headings to establish scope, not an outline, which will come later.
A quick reference for the Go command should be preserved in
As with the specification, updates to the quick reference on the website will be tied to the Go release cycle.
The following changes should be made to
Guide articles should teach developers how to accomplish specific tasks. Each article should focus on a specific topic or small group of related topics. Articles may be more verbose than reference documentation and should include more realistic examples.
Guide articles should be linked from the Learning Go section of golang.org/doc. See the Hosting section below for possible hosting locations.
The following is a non-exhaustive list of articles to be written.
The golang.org website is served using
The blog is served on a separate site, blog.golang.org using the binary
At the moment, there is no place for non-blog content to be published outside the Go release cycle. We are considering a few locations:
Whereever we end up hosting articles, authors should be able to write in Markdown or a similar convenient format, rather than raw HTML.