Why this session exists
You already write docs: READMEs, design notes, runbooks, that one wiki page nobody reads. This course makes them the kind people actually use, using the same sources Google trains its own engineers on. Every session works on one real artifact: Pulse, a small CSV-to-metrics pipeline that ships in this repo with working code and zero documentation. By Session 8 it has a doc set you'd be proud to inherit.
The good-docs formula 7 min live
Google's Technical Writing One opens with an equation, not a grammar rule. Everything you will ever decide about a doc - what to include, what to cut, which words need defining - falls out of this one line.
LiveAudience analysis in three questions3 min▶
Before writing anything, answer three questions in writing. Not in your head - in writing, at the top of your draft. It takes two minutes and changes every sentence that follows.
- Who are they? Their role, not their name: "data analysts new to the team", "the on-call engineer at 2am", "future me in six months".
- What do they already know? Assume real knowledge honestly. An analyst knows what a CSV is; do not explain it. They may not know your team's alert conventions; do explain those.
- What do they need to DO after reading? Docs exist so readers can act: run the pipeline, choose a config value, decide whether to page someone. If you can't name the action, you don't have a doc yet, you have a diary.
The two-audience README. A data team's README opened with an architecture philosophy essay (for engineers) followed by click-here screenshots (for analysts). Engineers skipped the screenshots, analysts bounced off the essay, and both groups DMed the author anyway. Split into a README plus a separate quickstart, the DMs stopped within a week. Same content, right gaps.
LiveThe curse of knowledge2 min▶
The curse of knowledge is the single biggest enemy of technical writing: once you understand something, you literally cannot remember what it was like not to understand it. The expert who built the pipeline is the worst-placed person to guess what a newcomer needs - and usually the person writing the doc.
You cannot cure it, but you can compensate:
- Name the assumed knowledge explicitly. "This guide assumes you can run Python scripts from a terminal" turns an invisible assumption into a checkable prerequisite.
- Test on a real newcomer. One fresh reader following your doc, while you stay silent, finds more gaps than three expert reviews.
- Watch for insider vocabulary. Every unexplained team-ism ("the staging thing", "Dana's fix") is a wall for the reader you claimed to write for.
Self-studyWriting for a global audience2 min read▶
Most technical docs are read by more non-native English speakers than native ones. Google's guidance is blunt: prefer simple words, short sentences, and zero idioms. "A piece of cake" costs a translation lookup; "easy" costs nothing.
- Drop cultural references and sports metaphors. "Hit it out of the park", "punt on this" and "the whole nine yards" all die in translation.
- Prefer standard American spelling and unambiguous date formats (2026-07-17, never 07/06/26).
- Simple vocabulary is not dumbed down. The technical terms stay exact; it's the connective tissue around them that gets plainer. "Utilize the aforementioned methodology" and "use this method" carry identical information.
Documents that declare themselves 6 min live
Readers give a new doc about thirty seconds before deciding to read on or close the tab. Good docs spend those seconds declaring three things: what this covers, what it doesn't, and who it's for. Google calls these scope, non-scope, and audience statements.
LiveState scope, non-scope and audience up front3 min▶
The highest-leverage sentences in any doc are the ones that tell the reader whether to keep reading. Google's pattern is three declarations, right at the top:
| Statement | Pattern | Pulse example |
|---|---|---|
| Scope | "This document explains how to..." | "This guide explains how to run the Pulse pipeline end to end." |
| Non-scope | "This document does not cover..." | "It does not cover adding new event types; see the reference." |
| Audience | "This document assumes you..." | "It assumes you can run Python scripts from a terminal." |
Non-scope statements feel like admitting weakness. They are the opposite: they save the wrong reader ten minutes, and they save you the support conversation afterwards. A doc that quietly hopes to serve everyone serves no one.
LiveFront-load the key point2 min▶
Busy readers read the first paragraph and the headings, then decide. Google's rule: state your key points at the START of the document - the conclusion, the recommendation, the one number that matters. Academic writing builds to a conclusion; technical writing leads with it.
- Page one is the whole doc for half your readers. Make sure the thing you'd most want them to know survives if they stop there.
- The same rule fractals down: the first sentence of each paragraph carries that paragraph (Session 3 makes this precise), and the first paragraph of the doc carries the doc.
The buried migration deadline. A platform team announced a breaking change in paragraph nine of a wiki page, after eight paragraphs of background. Three teams missed it and broke in production. The postmortem action item was one line: "put the deadline in the first sentence." Front-loading is an incident-prevention technique.
Self-studyCompare to what readers already know2 min read▶
The fastest way to teach a new concept is to anchor it to one the reader already has. Google recommends explicit comparisons early in a doc: "Pulse is like a tiny Airflow DAG with three fixed tasks" tells a data engineer 80% of the architecture in one sentence.
- Pick anchors from the audience statement. The comparison only works if the reader actually knows the anchor - this is the formula again.
- Say where the comparison breaks. "Unlike Airflow, there is no scheduler; you run the steps by hand" prevents the anchor from over-teaching.
Why write docs at all 4 min live
Write the Docs' beginner's guide makes the selfish case first: writing docs improves your own code and buys back your own time. The altruistic case (onboarding, bus factor) is real, but the selfish case is what gets docs written on a Tuesday afternoon.
LiveThe selfish case for documentation2 min▶
Four returns you collect personally, before anyone else benefits:
- Writing docs finds design flaws. Explaining an interface in prose is the cheapest usability test that exists. If the run order is hard to explain, the run order is the bug.
- Docs answer questions while you sleep. Every question a doc answers is a DM you never receive. The README you write once outworks the explanation you give weekly.
- Future you is a stranger. Six months from now you will know none of what you know today. The doc is a letter to that person.
- Docs make work legible to the people who rate it. An undocumented system is invisible in a promo packet; a documented one is an asset someone else can point at.
Self-studyBuilding doc mindshare in a team3 min read▶
Write the Docs has a change-management playbook for teams where "we should document this" always loses to the sprint. The moves, in order:
- State the problem with receipts: count the repeated questions, the onboarding weeks, the incident minutes lost to tribal knowledge. Make the cost visible before proposing the cure.
- Start where you are: one team, one system, one good doc set as the demo. Pulse plays exactly this role in this course.
- Make writing easy: templates, a known home for docs, and a norm that docs ship with the change (Session 7 wires this into CI).
- Keep a rhythm: docs reviewed in the same meetings as code, dead pages deleted on sight. A small set of fresh docs beats a large set of stale ones.
Meet Pulse, and feel the pain ★ 7 min · everyone follows
Pulse lives in this repo under pulse/: three Python scripts, a config file, sample data, and one NOTES.txt someone left behind. It works. It is also completely undocumented - on purpose. Your first job is to experience it as the newcomer.
Open the pulse/ folder and look at the file list only - no opening files yet. Guess: what does this thing do, and how would you run it?
Now try to answer three questions a new teammate would actually have, using anything in the folder: How do I run it, and in what order? Which event types are valid? What does the LOW alert on a day mean?
Time yourself. Note WHERE each answer was hiding: run order is implied by nothing, valid types hide in config.yaml, the alert logic hides in metrics.py.
Read NOTES.txt, the only prose in the folder. Every fact in it is true. Count how many times you have to re-read a clause to extract one fact - we fix exactly this in Session 2.
Write Pulse's audience statement ★ 7 min · build your own
Apply Part 1 for real: decide who Pulse's docs serve, in writing. This file becomes the first commit of the doc set, and every later doc gets checked against it.
Create docs/AUDIENCE.md in your copy of the repo (or any scratch file if you're reading along).
Fill in the template below. Be honest in the "already know" column - that honesty is the formula working.
Sanity-check with the gap test: for each audience, name one thing you must NOT waste their time explaining, and one thing you must never skip.
The doc plan: what Pulse needs, and when we build it ★ 8 min · build your own
With the audience written down, the doc list almost writes itself: match each audience action to the doc that serves it. This plan is also your map of the course - every line lands in a specific session.
Create docs/PLAN.md and copy the skeleton below.
For each doc, write one line: which audience it serves and what they can DO after reading. If you can't fill the action column, cut the doc.
Mark the one doc you'd write first if you only had an hour. (Almost everyone picks the README - which is why it's Session 4's milestone.)
The plan that killed a wiki. A team ran this exercise on their 40-page wiki and found 28 pages served no audience action at all - meeting notes fossilized as "documentation". They archived them, kept 12, and search suddenly worked. A doc plan is as much about what you refuse to write as what you write.
Try it yourself - this week ◐ 30-45 min total
- Run the two ★ Try it now exercises from Parts 1 and 2 on a doc you actually owe someone: the three audience questions, then the three scope statements.
- Finish
docs/AUDIENCE.mdanddocs/PLAN.mdfor Pulse if you didn't complete them live. - Find one doc at work with two audiences fighting inside it. Write the one-line split you'd propose (no need to actually split it yet).
- Read the two Self-study cards: global audience and doc mindshare. The mindshare playbook is the one you'll want the day your team asks "why are you spending time on docs?"
- Optional depth: Google's Technical Writing One audience and documents units are free at developers.google.com/tech-writing/one - this page covers their working content; the original has extra worked exercises.
Official sources covered
This session teaches the working content of these source units. What stays with the originals: Google's in-class facilitated exercises (facilitator guides are free) and the full Write the Docs guide prose.
Three questions before you go 🎯 ◐ 90 seconds
1 · The good-docs formula says a document should contain...
The subtraction is the whole trick. Option B without the subtraction is how you end up explaining CSVs to data engineers.
2 · Your doc keeps getting "quick question" DMs from people who clearly opened it. Most likely missing?
Readers who can't tell in 30 seconds whether the doc answers their question fall back to DMing the author. The declarations at the top are the fix.
3 · Which line in a doc plan should make you CUT the doc?
No action, no doc - that's Demo 3's rule. Small audiences and short docs are both fine; actionless docs are diaries.