Speaker: Ríona MacNamara, Staff Technical Writer, Google Event: Write the Docs

---

1. Introduction: The Winding Road to Tech Writing

Hi, I’m Ríona MacNamara. I’m a staff writer at Google—I’ve been there about eight years. Last year was my first time at Write the Docs, and what a year it has been! It has genuinely been the best year of my career, which spans about 20 years in technical writing. In terms of what we’ve accomplished and the team we built around internal engineering documentation at Google, it all started right here.

I love conferences like this because technical writers come from such diverse backgrounds. My own path to tech was definitely not direct:

• I started off studying English because I wanted to write the Great Irish Novel. By graduation, it became clear that wasn’t going to happen.

• Next, I went to law school thinking I’d be the "people's hero." By the end of law school, that clearly wasn't happening either.

• Then I moved to London to join literary publishing. I imagined nursing great novels into existence and attending parties with Salman Rushdie. Instead, I landed at Virgin Publishing, where I worked on books about Doctor Who, erotic fiction, and serial killers. (I’ve forgotten more about serial killers than you will ever know!)

• Later, I worked at Random House and then moved to Dublin to be managing editor at Attic Press, an influential feminist publishing house.

None of this had anything to do with technology until I took a two-week freelancing contract at Microsoft in Dublin editing content for Encarta World Atlas. That two-week gig turned into 10 years at Microsoft, where I eventually became International Editor for Encarta and moved to Redmond in 1998. After Microsoft, I spent 18 months at Amazon, and now I’ve been at Google for eight years.

I love my job. I’m one of those intolerable morning people who bounces out of bed before coffee, excited to open my laptop.

Except, this time last year, that wasn’t the case at all.

---

2. Burnout and the Science of Happiness at Work

A year ago, I was feeling deeply burned out. I kept wondering: Am I making an impact? Does my work actually matter?

Around that time, I came across Shawn Achor’s TED Talk, “The Happy Secret to Better Work.” We are raised to believe that if we work hard, success and happiness will follow. But Achor explains the reverse is true: happiness comes first. When we are happy:

• We are more creative, connected, and productive.

• Doctors make accurate diagnoses 31% faster when in a positive state of mind.

Achor outlines three key predictors of workplace happiness:

1. Optimism: The belief that your work matters, makes an impact, and is recognized.

2. Perception of Stress: Viewing stress as an energizing challenge rather than a paralyzing threat.

3. Connection: Feeling deeply connected to your colleagues, your work, and having influence over direction.

At the time, I was failing on all three counts.

---

3. The Documentation Crisis at Google

To understand why, you need to understand the scale of Google’s internal documentation challenge:

• 23,000 engineers.

• Hardly any internal technical writers. The ones we have are brilliant, but the reality is that engineers have to write and maintain their own documentation across thousands of shifting, interdependent systems.

• A fiercely autonomous engineering culture: Nobody can tell a Google engineer what to do. They choose their own tools, their own systems, and they hold very strong opinions.

The result was total fragmentation:

• Documentation lived scattered across Google Sites, Google Docs, wikis, and random HTML pages.

• Much of it was unmaintained, unreliable, or nonexistent.

• In Google’s annual company-wide survey—which leadership takes very seriously—the #1 blocker to engineering productivity two years in a row was the lack of discoverable, reliable internal documentation.

We had tried fixing this before:

• Top-down mandates didn’t work (engineers ignored them).

• Bottom-up efforts didn’t scale (we’d polish a team’s docs into an exemplar, but the moment we walked away, the docs decayed).

On top of that, I had recently been promoted. Instead of feeling relaxed, my imposter syndrome spiked. I felt isolated, stressed, and convinced my efforts weren't moving the needle.

---

4. The Write the Docs Epiphany

Then, I came to Write the Docs last year.

Two talks in particular stood out, especially one from Twitter explaining how they co-located documentation with code, alongside another talk on Minimum Viable Documentation.

I remember furiously instant-messaging my coworker, Aaron, in our New York office:

"They have the exact same problem we do, and they solved it by putting docs in the repository with the code!"

When we got back, Aaron and I—both between projects—decided to dig into the problem from scratch. We interviewed as many engineers as possible. We quickly realized our core mistake:

All our previous documentation solutions had been designed for writers. But technical writers weren't the primary users—engineers were.

The root issue was architectural:

• Google has one of the largest integrated monorepos in the world, with tens of thousands of engineers committing to it every day.

• Code lived in this tightly managed, unified repository.

• Docs lived everywhere else: in a Google Doc, on a wiki, or on a sticky note.

Documentation would never become part of Google’s engineering culture until it lived in the codebase and integrated directly into the engineering workflow.

---

5. Going "Five Blades": The Birth of g3doc

We didn’t want to build just another competing content management system. Inspired by The Onion’s satire piece ("Fuck Everything, We're Doing Five Blades"), our code name became Five Blades: we were going to go all-in or go home. We wanted a system that could become the standard for all 23,000 engineers.

Our vision was radically simple:

1. Allow engineers to write docs in Markdown right alongside their code in the codebase.

2. Render those files automatically at a clean, predictable intranet URL.

3. Keep the barrier to entry near zero.

There was one technical catch: Google’s internal doc-serving system couldn't read directly from the core codebase.

Having nothing to lose, we emailed Steve, an engineer in Munich who ran that infrastructure: "Hey, could we render docs straight out of the repo?"

Because of the time difference, I woke up the next morning to find that Steve had already written a design doc, scheduled a security review, and laid out the architecture. Within nine days, we had a working proof of concept.

Project g3doc was born.

Our branding was intentionally minimal: just a terminal prompt. Drop Markdown files into your directory, add a simple sitemap.md for navigation, and g3doc rendered code formatting, dynamic tables of contents, and page metadata out of the box.

On July 8th, we launched our first live site for a core infrastructure system. The developer reaction was immediate:

"This is the best thing ever."

---

6. Viral Adoption and Culture Shift

Within weeks, 18 projects migrated. We only actively pitched three of them; the rest spread purely by word-of-mouth.

Other technical writers facing massive scale joined the effort—Ed from Search Infra, Ricardo from Ads, and Theodore, who was supporting a team of 300 developers across dozens of projects. We operated with open-source principles: governance belongs to the contributors.

We established two core cultural rules for our team:

1. Focus relentlessly on the engineer. Every feature had to respect developer workflows.

2. No "cookie licking." (Cookie licking is when someone claims an interesting feature by touching it, but never finishes it, preventing anyone else from doing it.) We prioritized momentum, rapid iteration, and immediate impact.

Next, we partnered with Google’s Developer Infrastructure team to embed g3doc into the core developer toolchain:

• Code search

• Code editor

• Code review tools

Engineers could now preview rendered documentation directly within code reviews with a single click.

The Numbers:

• September: 18 projects

• December: ~160 projects

• Q1 Goal: 300 projects (an aggressive OKR)

• Actual Q1 Result: 930 projects

• Today: Over 1,600 projects

Most of the team building and scaling g3doc were 20% volunteers. It evolved from a scrappy grassroots effort into core company infrastructure.

---

7. Lessons Learned

1. Focus on the engineer’s workflow, not the writer’s.

In an environment where engineers own the docs, you cannot expect them to adopt a technical writer’s toolset. Meet them where they already live: inside their repository, editor, and review tools.

2. Momentum matters: Start small and iterate.

Don’t over-engineer a massive CMS upfront. Build a rock-solid, minimalist base platform, launch it quickly, and add features based on real developer demand.

3. Claim authority through solving real problems.

Between us, our team had decades of technical writing expertise in information architecture, layout, and style. But none of that mattered until we solved the engineers' core problem. Nobody was going to invite us to "fix their docs."

Once we fixed the workflow, we didn’t just gain adoption—we gained influence. Senior engineering directors began reaching out, funding our efforts, and inviting us to strategic architectural discussions.

---

8. Closing: A Happiness Check-in

Revisiting Shawn Achor’s predictors of happiness:

• Optimism: Massive. Thousands of changelists (CLs) are submitted every day where engineers update code and documentation in the exact same commit. Docs are finally part of the engineering culture.

• Perception of Stress: I work hard, but I feel less stressed than ever because the work is self-directed, purposeful, and demonstrably impactful.

• Connection: Unprecedented. We moved from isolated writers to trusted partners seated at the table with principal engineers.

A few months ago, Aaron and I were in a meeting with senior engineering leaders in New York discussing a major codebase-wide integration for g3doc. One engineer noted, "This might require a global policy shift across the monorepo."

A principal engineer leaned back and said:

"Well, three of the five people in this room are global approvers of the codebase. I don't think that's going to be a problem."

Right then, my phone buzzed. It was a text from Aaron sitting across the table:

"We did it."

Authority and influence are out there for technical writers—they are ours for the taking if we focus on our users, step up, and solve real engineering problems.

Go five blades. Be happy. Thank you!

---

Key Takeaways Summary

• Docs as Code Works: Placing documentation in the same repository as the code ensures docs are updated, reviewed, and versioned simultaneously with code changes.

• User-Centric Tooling: For internal engineering docs, the engineer is the user. Markdown + Git/Monorepo + existing review tools will beat an external wiki or CMS every time.

• Grassroots Credibility: Don't wait for top-down mandates. Build a lightweight, reliable prototype, prove value, and let peer adoption drive culture change.