Documentation-first programming: what it means for technical writers

A familiar argument, now heard in the right room

I recently read an interesting article called Documentation-first programming on the Negroni Venture Studios website. The central argument of the post, which has been doing the rounds in tech writing circles, is simple and, for anyone who has worked in technical writing, it probably rings a bell: the specification is the program. The code is a disposable byproduct.

The author, Alasdair Allan, came to this conclusion by building a programming language designed for machines to write. Every function requires a formal contract: what it needs, what it guarantees, what effects it performs. The compiler proves these contracts hold. No variable names, no style choices, one canonical form. And what does the human write? Contracts. Specifications. Documentation.

He observes that this is the work developers have often tried to avoid. It’s an ironic twist: the part of the job that many developers hate is about to become the whole job.

I wrote about something related back in December in a post called Beyond documentation: tech writers as strategic enablers. I argued that the job of a technical writer was never really just producing manuals. We do so much more than that, we are knowledge engineers, product thinkers, and quality guardians. Allan’s article makes the same case, although arriving from a different direction.

The bottleneck was always the specification

Allan references formal verification research to make a pointed observation: proofs can be automated, code can be generated, but someone still has to write down what “correct” means. That bottleneck is human. It has always been human. We just hid it behind the mechanical act of writing the code itself.

American computer scientist Fred Brooks named this in 1986 in his paper "No Silver Bullet — Essence and Accident in Software Engineering": the hardest part of building software is deciding precisely what to build. Every tool that reduces the accidental complexity of software — high-level languages, compilers, AI code generation — just makes the essential complexity more visible. AI has now stripped away enough accidental complexity that the essential part, the specification, is impossible to ignore.

This is a core technical writing competency. Extracting tacit knowledge. Making implicit constraints explicit. Structuring decisions for an audience — human or machine — that wasn’t present when the decisions were made. Technical writers have been doing this work for years.

None of this is entirely new. The core philosophy of spec-driven development — the practice of writing formal specifications before writing code — has existed as a methodology for a some time. That said, the modern implementation has exploded in popularity recently as a direct response to AI coding tools. GitHub even maintains a Spec Kit: a kind of practical framework for writing engineering specs. What Allan’s article does is less introduce the idea and more confirm that it is no longer optional. AI hasn’t invented the need for specifications; it has more likely removed the excuse for skipping them.

Cognitive debt and context rot

Allan talks about two interesting terms. The first is cognitive debt: not the technical debt where you cut a corner knowing you cut it, but the deeper problem where code looks clean, passes tests, ships to production, and then breaks in ways nobody can diagnose. The gap between what the codebase does and what the team knows about it.

The second is context rot: stale documentation that an AI system cannot distinguish from current guidance. The Amazon retail outage Allan describes is a context failure in its purest form. A wiki page wasn’t wrong when it was written; it became wrong over time. No one updated it, no one marked it obsolete, and when an AI tool ingested it, it treated historical guidance and current operational reality with equal weight. An engineer followed the advice. The site went down.

Both of these are documentation problems. Both are preventable with the kind of systematic content ownership that technical writers are specifically trained for. If your documentation is nobody’s job, or is treated as an afterthought after code ships, you are accumulating cognitive debt and context rot simultaneously.

The theme of lean, accurate, and easy to maintain documentation in the age of AI is also explored in this fantastic talk by Aileen Mary at Write the Docs Portland 2026. I highly recommend it.

The job market has already priced this in

Allan points to something I find interesting in the hiring data too. Engineering and product manager roles are up roughly 75–78% from the 2023 trough. Design roles are flat. His interpretation: the implementation layer is being commoditised; the specification layer is becoming more valuable. PMs deal in requirements and strategy. Engineers increasingly deal in system design, integration, and maintenance. Both are specification work.

Technical writing roles that operate closer to the specification end of the spectrum — information architecture, content strategy, API design, developer experience — are in the same trajectory as PM roles. Technical writing roles that operate primarily as post-hoc documentation of finished products are more in the realm of visual design.

Going even further upstream

The article distinguishes between two approaches to documentation-first. Manny Silva’s “Docs as Tests” methodology treats documentation as a mirror of the product: you build, then you verify the docs match what was built. Allan says that this is perhaps “coming at it from the wrong end.”

The documentation-first thesis is more radical. Documentation is the source, not the reflection. The specification comes before the code. The contracts define what the system should and shouldn’t do. The code is generated from those contracts, not the other way around.

For technical writers, this is both a challenge and an opportunity. The challenge: it requires moving perhaps even further upstream than ever before — not to own the specification, but to be present when it is written.

Ownership of the spec belongs with engineering managers and product owners. They are accountable for what gets built and why, and that accountability shouldn’t move. But owning something and writing it well are different skills. Specs are often drafted by people who are excellent at designing systems but less practised at writing with precision, eliminating ambiguity, or thinking about how the document will be read and used months later by someone who wasn’t in the room.

That is the kind of gap that technical writers are trained to fill. The practical implication isn’t that TWs should take over the spec — it’s that TWs should be sitting with engineering managers early, asking the questions that expose gaps, making implicit decisions explicit, and ensuring the specification is clear enough to actually do its job. We know how to ask “what should this actually do?” and “what does correct look like from the user’s perspective?” before a single line of code is written. Those are specification questions, and we should be in the room when they are answered.

In many aspects, this is what’s already happening in teams that collaborate in docs-as-code workflows. It could be that AI is just making this even more pertinent.

Are we programmers now?

Here’s where I find myself without a fully-fledged answer.

It’s a question that raises real concerns about accountability too. If the specification generates the code, then spec quality is directly responsible for system quality. If the spec is ambiguous, the generated code will be wrong in ways that trace back to the spec. If the spec is stale, the system rots. Those failure modes have always existed — but in a world where code was “hand-written”, a skilled engineer could compensate for a vague spec through judgment and experience. In a documentation-first world, that compensating layer is gone. The spec is the thing. Which means the people who review it, challenge it, and maintain it carry real weight — even if they don’t own it.

I’m not sure if “are we programmers?” is quite the right question though. I think the more honest framing is: what is programming becoming? And the answer, if Allan is right, is something that looks a lot more like what technical writers have always done: reasoning carefully about what a system should do, for an audience that wasn’t present when the decisions were made, in a form that survives long enough to be useful.

If that’s programming, then perhaps we’ve been doing a version of it for years. What’s changed is that the tools now make it legible to the rest of the industry.

But there’s an important caveat here. The specification is the program, but is it also the documentation? A formal contract that says a function must return a sorted list and must not perform I/O is precise, verifiable, and machine-readable. It tells a compiler what to prove. It doesn’t tell a user how to find their invoice, or why a particular workflow behaves the way it does, or what to do when something goes wrong. Technical writers have always worked in both registers simultaneously: the precise, structural language of specifications, and the contextual, human language of explanation. That dual role — spec author upstream, user advocate downstream — doesn’t collapse in a documentation-first world. If anything, it sharpens. The gap between what a system formally does and what a user actually needs to understand is not going away. Someone still has to bridge it.

The specification is also ours

Allan closes with the observation that experience only lives in one head at a time. Technical writing exists, in part, to fix that. We have always been the mechanism by which institutional knowledge becomes durable, transferable, and maintainable.

AI has changed what code costs. It has not changed what clarity costs. Articulating what a system should do — precisely, consistently, and in a form that survives the departure of the person who originally knew — remains genuinely hard. It requires judgment, domain understanding, and the ability to reason about audiences who are not in the room.

Those have always been technical writing skills. They are also, whether the industry fully recognises it or not, core engineering skills.