Technical Documentation Is the New Source Code

How technical documentation has become a core asset — as central to the developer experience as the codebase itself.

In an age of Large Language Models and executable specifications, technical documentation is no longer a second-class citizen. It is the interface, the architecture, and increasingly, the source code itself.

This isn’t a metaphor. It’s a real shift — one that’s both technological and philosophical — and it describes the arc of my own career.

From code to context

There’s a reason I’ve moved through the titles of Senior Software Engineer, Product Manager, and Technical Writer. Titles can be creatively limiting — I still think of myself as an engineer — but behind the changes lies a deeper progression:

Writing code → Designing systems → Designing products → Describing systems and products

That final step — describing — has never been an afterthought. It’s not “just documentation.” It’s the essential connective tissue that makes complex systems understandable, buildable, and now, automatable.

Documentation has always been technical

For too long, “documentation” has been treated as something done at the end — a chore, an obligation, a footnote. But truly effective documentation is technical thinking, formalised in language.

It spans the entire lifecycle: problem definition, systems modelling, architecture, implementation, testing, deployment. It’s any form of writing or diagramming that communicates what we’re building and why.

By that measure, even source code is documentation.

Source code is documentation

Code isn’t written in binary. It’s written in human-readable languages, with meaningful structure, logical flow, descriptive naming, and in-line commentary. The purpose isn’t just to instruct the machine — it’s to communicate intent to other humans (and increasingly, to AIs).

When you decompile a binary, you lose all that. What’s missing isn’t the logic — it’s the language. That’s what makes code readable, maintainable, and collaborative. That’s what makes it documentation.

So the distinction we make between source code and docs? It’s thinner than we admit.

The automation curve

Earlier in my career, I worked as a hands-on software engineer in small companies where I did everything: user research, system modelling, architecture, implementation, testing, deployment. It was creative, full-spectrum engineering — and I loved it.

But as teams scale, roles specialise. The “software engineer” becomes the “software developer,” tasked with delivering a narrow slice of functionality in a tightly constrained system. Frameworks, toolchains, review processes — all essential, but all contributing to a sense of commoditisation.

Repetition invites automation. And automation is what engineers do. Whether it’s a for-loop, a CI/CD pipeline, or a machine learning model, the goal is the same: abstract complexity and eliminate repetition.

Which brings us to today’s AI revolution.

LLMs and the rise of executable documentation

With the rise of Large Language Models (LLMs), we’ve entered a new phase. What used to be a static technical spec can now be a live, interactive, executable prompt.

Documentation isn’t just reference material anymore — it’s the interface to the machine.

And the difference between source code and documentation? It just vanished. AI executes on your prose. When you write a system design, you’re writing code-by-proxy. Prompt engineering isn’t a gimmick — it’s a new form of programming.

And who’s best equipped to write prompts with precision, clarity, and intent?

People who know how to think, speak, and write technically.

We’re not replacing developers — we’re redefining development

Low-level code generation may be getting automated. But the need for technical clarity, system-level thinking, and executable specifications has never been more acute.

That’s why technical writing is a superpower.

Finding the right label

I’ve worn the titles of software engineer, product manager, and technical writer. I don’t know exactly what label will come next — and I’m not sure it matters — but I know I’ll be working at the boundary between how things work and how they’re understood.

Whether it’s defining APIs, designing systems, or writing documentation that enables others to build confidently, I thrive in the space where clarity meets complexity — and where communication is just as technical as code.

This is the shift

AI isn’t a break from the past. It’s the continuation of a centuries-old trend toward abstraction and automation. What’s changing is the interface.

Where we once wrote code, we now write specifications. Where we once had compilers, we now have models. And where we once dismissed documentation, we now realise:

Documentation is the new source code.

---

If you’d like to share your own experiences or thoughts, feel free to connect with me on LinkedIn or email me at mike@myglassesaredirty.com.