Repository: go
Issue: proposal: x/pkgsite: package tours (additional documentation type for packages)
Labels: Documentation,Proposal

### Proposal Details

## Background

Go packages can have two distinct forms of documentation:

1. Comments anchored to identifiers as described by [_Godoc: documenting Go code_](https://go.dev/blog/godoc) and [_Go Doc Comments_](https://tip.golang.org/doc/comment).

2. Runnable (API) examples as described by [_Testable Examples in Go_](https://go.dev/blog/examples)

Both of these are rendered in [godoc](https://pkg.go.dev/golang.org/x/tools/cmd/godoc) and [pkgsite](https://pkg.go.dev/golang.org/x/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](https://www.reddit.com/r/golang/comments/1f03h22/my_grievances_with_go_documentation/), 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_](https://go.dev/tour/welcome/1)?  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](https://cs.opensource.google/go/x/website/+/master: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):

<img width="402" alt="Bildschirmfoto 2024-09-04 um 14 12 06" src="https://github.com/user-attachments/assets/9e28b392-12ad-4598-a118-7e8ccb8a4b96">

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](https://pkg.go.dev/golang.org/x/tools/present) tool, too.

## Rejected Alternatives

There is technically a third form available: the blog post (e.g., [_Go Concurrency Patterns: Context_](https://go.dev/blog/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.