Proposal Details

Background

Go packages can have two distinct forms of documentation:

1. Comments anchored to identifiers as described by Godoc: documenting Go code and Go Doc Comments.

2. Runnable (API) examples as described by Testable Examples in Go

Both of these are rendered in godoc and pkgsite.

These two forms of documentation serve somewhat overlapping/disjoint purposes:

• Go documentation comments are mostly in the vein of reference manual.
• Runnable (API) examples are minimal viable demonstrations of an API at the very least to sometimes complete end-to-end examples (which it is is predicated by how complicate the API is to work with).

Problem

In this public discussion, it became clear that a type of documentation is missing for users: step-by-step tutorials or material that focuses on an end-to-end developer journey. This led to a thought about how we could fix this gap in a nice Go-like way.

Proposal

What if we expanded the documentation servers to enable users to create their own API tours à la A Tour of Go? A package could have multiple tours to demonstrate the journeys.

Imagine a hypothetical Go module at github.com/matttproud/rot13 that follows a directory structure like this:

$ tree rot13
rot13
├── cmd
│   └── rot13
│       ├── rot13.go
│       ├── rot13_test.go
│       └── rot13_x_test.go
├── endtoend
│   ├── endtoend_test.go
│   └── testdata
│       ├── input.txt
│       └── output.txt
├── go.mod
├── rot13.go
├── rot13_test.go
└── rot13_x_test.go

We could have a directory structure like this:

rot13
│   … earlier elements elided …
├── tours
│   ├── basic.article
│   └── advanced.article
│   … later elements elided …

Then the respective documentation servers would have some sort of internal support to run tours (e.g., use what binary tour uses). When viewing the respective package in the viewer, the table of contents for the package would also include a heading that lists sub-elements of available tours (tracer shot):

This has the advantage of keeping the documentation for extended workflows adjacent to the code so that it can be always fresh.

Perhaps this could even be extended to support the present tool, too.

Rejected Alternatives

There is technically a third form available: the blog post (e.g., Go Concurrency Patterns: Context), but …

1. these blog posts are seldom back-linked to the Go package documentation.
2. findability is not great either with the blog posts (especially older ones).
3. sometimes the blog posts are superseded with new information/methodologies.