Documentation as Code
When infrastructure becomes a system of thought
The Problem
When I joined Google in 2012, the company had about 10,000 engineers and was growing rapidly. Documentation lived primarily in Goowiki—a custom set of scripts that integrated with Google's infrastructure.
Wikis are fundamentally unstructured. Because people aren't natural information architects, wikis quickly become labyrinthine. At scale, they become more harmful than useless: broken conceptual links proliferate, information threads follow paths that are not obvious, and no one knows if what they're reading is current. If you’ve ever used Notion, you know what I mean.
The cost of maintaining Goowiki compounded as Google grew. Onboarding slowed because everything was poorly documented, and those documents were impossible to find. Engineers wasted time searching or, worse, rebuilding knowledge that already existed somewhere. A slower pace meant higher costs.
Meanwhile, Google's infrastructure was changing and the people maintaining Goowiki couldn't keep up. We needed to shut it down, but we had nothing to replace it.
The Insight
Three separate innovations converged:
1. I developed a facilitation technique that let me collaborate productively with software engineers. What might have taken 6-9 months could be completed in about a month with one day of input from a small team. This enabled me to document systems like the auction in Display Ads, which implemented the notoriously subtle Vickrey-Clarke-Groves algorithm—work that saved a whole class of engineers weeks of meetings and reviews.
2. Some of my colleagues had a genius idea: why not put a web server in front of Google's code repository (google3), and serve Markdown files as documentation. The brilliance was simple:
- Engineers already navigated the source repository daily. Putting docs beside code meant they always knew where to find them.
- Same toolchain that engineers used for code—zero cognitive load to extend their work to docs, no context switching.
- Physical proximity created logical proximity: documentation lived where it was relevant.
3. I developed a writing course specifically for software engineers—not teaching writing in a writerly way, but using their cultural primitives. Instead of approaching writing as an academic concept, I treated English as one more formal system in their toolbox. Engineers code-switch between formal systems constantly: programming languages, configuration, system architecture. English was just another ruleset.
Documentation isn't a content problem.
It's an infrastructure problem.
What Was Built
We called it g3doc. The infrastructure was simple: Markdown files in the code repository, a web server to render them, and publishing tools that made it stupidly easy to create beautiful documentation without wrestling with configuration.
The adoption was anything but simple. Engineers had to believe documentation was worth their time, know how to write clearly, and trust they could find what they needed when they needed it.
That's where the three pieces came together:
- My facilitation technique meant teams could produce comprehensive documentation in weeks instead of months. When a team saw their complex system explained clearly—and saw other engineers using those docs to avoid weeks of meetings—documentation stopped feeling like overhead and started feeling like leverage.
- The Technical Writing course gave engineers the tools to write well without becoming writers. We taught thousands of Googlers how to treat documentation like code: clear, maintainable, debuggable. The course later became publicly available as Technical Writing One at developers.google.com, where it's been adopted by companies like GitLab.
- The g3doc infrastructure meant engineers never had to leave their workflow. Write Markdown beside your code, commit it with your changes, done. Documentation became part of the development process, not a separate task requiring different tools and different thinking.
The results: my team grew from serving 300 engineers in Display Ads to supporting 2,500 across the organization. Engineers adopted g3doc quickly enough that Google shut down Goowiki. The g3doc team got formal funding and headcount to maintain the infrastructure.
Most importantly, we solved the core problem: engineers could find accurate, current documentation because it lived where they already looked—right next to the code.
How it propogated
Engineers adopted g3doc fast enough that Google shut down Goowiki within about 18 months. The pattern became standard across Google engineering documentation living beside code, maintained with the same tools and workflows.
But the approach resonated beyond Google. In 2015, Riona McNamara presented g3doc's methodology at Write the Docs in Portland. That presentation helped catalyze what became known industry-wide as "docs as code"—a fundamental shift in how software organizations think about documentation infrastructure.
The approach spread: GitHub, GitLab, and others adopted similar patterns. Companies now point to Technical Writing One (the public version of my engineering writing course) as a foundation for their documentation practices.
In 2017, the CACM published a paper that I co-authored on the facilitation technique that made rapid, high-quality documentation possible. Peer-reviewed validation from a top-tier journal, alongside heavyweight academics, for work that had started as a practical necessity at Google.
Most importantly, we'd solved a problem that every scaling engineering organization faces: how to make knowledge production and retrieval actually work. The solution—treat docs like code—seems obvious in retrospect. It wasn't obvious in 2012.
How it propogated
This work required recognizing when separate innovations solve different parts of the same problem—and having the technical range to integrate them into something coherent.
The facilitation technique addressed content quality. The infrastructure addressed workflow friction. The writing course addressed skill gaps. None of these alone would have transformed how Google documented its systems. Together, they created a complete solution.
It's work well-suited to problems where the bottleneck isn't any single thing it's how the pieces interact. When engineers can't find documentation, the problem isn't just bad search or bad writing or clunky tools. It's that those three failures reinforce each other. Fix one and the others drag you back down. Fix all three simultaneously and the whole system shifts.