(2022-10-26) Udell Literate Programming In Go

Jon Udell: Literate programming in Go. During a recent company hackathon, my team's charter was to improve the documentation for the Steampipe plugin SDK

*As is typical, the documentation was an autogenerated catalog of functions and types. To explain how to use those functions and types, we provided guidance on the steampipe.io site.

Our hackathon challenge was to weave such guidance into the generated documentation.*

*Steampipe lead developer Kai Daguerre noticed that our top-level page lacked the overview section he saw in the documentation for pgx, a Go driver for Postgres.

That overview comes from https://github.com/jackc/pgx/blob/master/doc.go, which is one long comment (that uses Go comment syntax) followed by a package declaration.*

So we added a doc.go at the top level of our repo to produce this overview.

it's a valid Go file that belongs to a package. The package contains no code, only documentation

The ability to link within the code's namespace was a revelation

the bracketed items render as links to a type, plugin.HydrateFunc``, and to a property,plugin.Column.Hydrate``. This was starting to feel like wiki writing!

What we still lacked, though, was the ability to create new wiki pages where we could explain higher-level concepts.

Kai realized that not only could we create new documentation-only packages for such topics, we could also import them

How is this literate programming? It isn't!

Our modern ways of mixing code and documentation, and generating docs from embedded comments, only superficially resemble Knuth's practice, as Mark Jason Dominus pointed out in his essay POD is not Literate Programming (2000).

And yet, now that our hackathon exercise has given me a taste of what code-as-wiki can be, it does feel like a step toward the storytelling approach that Knuth advocates.