When to take the helm back: retiring a docs pipeline once the work turns editorial

Docs-as-code trains one reflex above all others: when a task repeats, automate it. Single-source the content, generate the output, and never touch the generated file. The reflex is right often enough that it stops feeling like a decision. But there is a rarer, harder move that the same discipline should include and almost never talks about - dissolving a pipeline you built once it has stopped paying for itself.

I hit that point recently on a 356-page LaTeX book. The generator worked. It was well-behaved. And deleting it was the right call. Here is how I knew.

The pipeline I built, and why it was right at first

The book started as a machine-made object, on purpose. There was one hand-owned source file - the raw body - and a 453-line Python generator that read it and wrote the file LaTeX actually compiled. Between the two, the generator did the mechanical work no human should do by hand across a whole book:

injected an index of 200-odd entries (the index itself built by an LLM pass, the same way I’d done it for an earlier volume),
wired up a \gls glossary, marking the first occurrence of each defined term,
and attached a birth-death footnote to the first mention of each real person, with the dates pulled from Wikidata by a separate lookup script.

The output was a 5,684-line generated file. The rule was the ordinary docs-as-code rule: you never edit that file, because the next build overwrites it. You edit the raw source and regenerate.

This was the correct design, and I would make the same choice again. Every one of those transformations was systematic: the same rule applied hundreds of times across the text, consistently, in a way that is tedious and error-prone by hand and trivial for a generator. That is exactly the shape of problem automation is for.

When the work changed shape

Then the book was mostly built, and the work changed character without announcing itself. The remaining edits were no longer rules that applied hundreds of times. They were judgments about single passages:

a word set in full capitals for emphasis should be italics instead - but only this word, in this sentence;
a run of quoted speech should become an indented dialogue block, this quote, not all quotes;
two acronyms should be spaced small caps, and a chemical formula should carry a subscript;
a drop cap should be followed by small caps on the opening words of a paragraph.

None of these is a rule. Each is a decision about one place in the text, made by looking at that place. There is no pattern to encode because the whole point is that each case is particular. This is editorial work, and it is the opposite of what the pipeline was good at.

The tax a pipeline charges on editorial work

A generator that pays for itself on systematic work quietly reverses sign on editorial work. To change one word’s emphasis I now had to edit the raw source and regenerate 5,684 lines to see one character change - or, worse, feel the pull to edit the generated file directly, the one thing the whole discipline exists to forbid. The layer that had guaranteed consistency across hundreds of insertions was now just sitting between me and the text, taxing every small human decision.

The pipeline had not gotten worse. The work had moved out from under it.

Taking the helm back

So I dissolved it. I ran the generator one last time, froze its output inline into the raw source, and deleted the generator and every generated file. The main file now reads one hand-owned source directly - a single \input, no Python step in the build at all. The compile went from source-plus-generator to plain LuaLaTeX, and produced the same 356 pages with no errors.

Since then, every typographic edit has been what editorial work should be: open one file that I own, change the passage, rebuild. The italics, the dialogue blocks, the small caps, the subscript - each is a two-line diff against text I read and edit directly, with nothing translating between my intent and the source.

What I kept automated, which is the real line

The important part is what I did not delete. The scripts that gathered the index and looked up the birth-death dates on Wikidata still exist. They still run - but as one-shot generators that produce a committed artifact I then own outright: a JSON file, a block of text frozen into the source. They are not a live layer the build depends on.

That is the line worth drawing:

Automate bulk, mechanical, repeated work whose output you freeze and own. The date lookups, the LLM index pass - run once, commit the result, done.
Retire a live transformation layer once the marginal edit has become human judgment. When the next change is editorial rather than systematic, a generator standing between you and the source is a cost, not a safeguard.

It is the difference between the autopilot and the helm. Autopilot earns its keep on the long mechanical reach across open water. You take the helm back for the harbor approach, where every adjustment is a judgment made by looking at exactly where you are.

The more common mistake

I want to be careful, because this post argues for the unusual direction and the usual direction is still right most of the time. The far more common error in documentation work is taking the helm too early - hand-editing what should be generated, copy-pasting what should be single-sourced, doing by hand the tedious repeated work a fifty-line script would do correctly forever. If you are not sure which situation you are in, you are probably in that one, and the answer is to automate.

The move this post is about is the rarer reverse, and it has one specific trigger: the work has stopped being systematic and become editorial, and the pipeline is now taxing every human decision instead of removing tedium. That is when you take the helm back.

Summing up

Signals that a docs pipeline has outlived its job:

The last several changes were one-off judgments about single passages, not rules applied many times.
You regenerate a large output to see a one-character change.
You feel the pull to edit the generated file directly - the discipline is fighting you rather than helping.
The generator’s remaining value is historical: it built something once that no longer changes systematically.

When those line up, freeze the output, delete the generator, and edit the source by hand. Keep the one-shot scripts that gather data into committed artifacts. Automation is a tool for systematic work; when the work turns editorial, the most disciplined thing you can do is take the helm back.

External sources

Hero image: “Helm, HMS Gannet” by EEPaul, licensed under CC BY 2.0.