The Documentation Was a Dogfood Too

There comes a point where making a language more capable stops being the highest-value work. The probes of the previous part had reached exactly that verdict: the core was mature, and digging further turned up no pain sharp enough to force a change. So the centre of gravity moved — from building the language to making it usable and legible. The prompt for the shift was slightly embarrassing. Earlier in the series, the author had reached for a language feature and momentarily forgotten it existed — missed his own list-literal syntax — which is a small, honest demonstration of a real principle: a feature that cannot be found is, for all practical purposes, a feature that is not there. The next job was discoverability, and its first artifact was a tour.

A tour, verified

The reference documentation was already thorough, and the tutorials were already careful, but neither of them let a newcomer see the whole language quickly. A reference is exhaustive by design; a tutorial is a sequence of steps. What was missing was the form the Go community made familiar — a single page that shows everything at once, each feature in the smallest example that demonstrates it. So a tour was written: expressions and curried functions, mutual recursion, algebraic data types and matching, records, list literals and comprehensions and patterns, tuples, strings and interpolation, the structural rendering and JSON and equality from the previous part, modules and imports, capability effects — the language at a glance, and every example on the page run through the interpreter first so that nothing shown was aspirational. A tour is a strange document to need, because it teaches nothing a determined reader couldn’t assemble from the reference. But it is the difference between a language that can be learned and one that can be seen, and seeing comes first.

Writing the docs with the language’s own tools

The move that made this part more than housekeeping is that the documentation site is not built by some off-the-shelf tool. It is built by a static site generator written in Mere, part of the language’s own library collection, which turns a directory of Markdown into a set of HTML pages. So producing the documentation was, unavoidably, a dogfood of the generator — every page of docs run through a program written in the language the docs describe. The site gained a curated ordering, grouping pages into sections rather than listing them alphabetically, showing each page under its real title rather than its filename, and — a small piece of care that matters over time — a safety net that automatically appends any uncatalogued page to the end, so that a newly written document can never silently vanish from the site by being forgotten in the ordering.

What the tool found when it was used

Being used in earnest is what makes a tool honest, and the generator immediately reported on itself. Several library files, when imported, ran demonstration code and printed it to standard output — a pattern that had been caught and fixed before in other libraries and had quietly recurred in these. A file that runs a demo when you import it is not a library; it is a script wearing a library’s clothes, and its output showed up uninvited in the middle of a site build. They were trimmed back to definitions only. A smaller thing: string interpolation did not automatically render a number, so a value spliced into a string needed to be turned into text explicitly. Each of these was found not by review but by use, which is the only place they could have been found.

The comma, and the smallest possible loop

The sharpest finding was the smallest. Writing the site generator’s own source hit a piece of missing syntax: a trailing comma after the last element of a list or a tuple — the comma you leave in so that adding the next line is a one-line change — was rejected by the parser. It is a papercut, but it is the kind of papercut that a person writing real code meets constantly, and it had been invisible until real code was being written. The parser was taught to accept it, which turned out to be a two-branch change and, in a pleasant confirmation that the design was already consistent, records had accepted a trailing comma all along. This is the dogfood loop at its tightest: a program is written, the writing meets friction, the friction becomes a fix in the language, and the fix ships — except here the program being written was the documentation site, and the whole turn closed almost at once. The loop does not require a grand application. Writing about the language, in the language, was enough to improve it.

A front door of its own

The last piece was not technical but it mattered: the site moved to a name of its own, a proper domain rather than a project path under a host’s shared address, with the old address redirecting to the new one so no existing link would break. The build regenerates the interactive playground pages as part of every deploy, so the compiler-in-the-browser demos stay in step with the compiler itself. A language that had spent its whole existence as an internal project now had a front door — a landing page that starts by pointing a visitor at the tour, a set of documents in a deliberate order, and an address you could actually say out loud.

None of this made the language more powerful, and that was the point. It made the language reachable, which is a different axis and, at this stage, the more valuable one. And it did so while staying inside the same discipline as everything before it: the docs were built with the language’s own tools, so improving the docs and improving the language turned out to be the same activity, one loop, closed one comma at a time.