Why this session exists
Seven sessions in, Pulse has every doc from the Session 1 plan: audience statement, README, how-to, reference, ADR, changelog, and a docs-as-code pipeline that lints it all. What it doesn't have yet is a final quality pass. Drafting and editing are different jobs done in different mindsets, and today we do the second job properly - then we ship.
The editing pass 6 min live
You cannot draft and edit in the same sitting with the same brain. Google's self-editing unit gives six tactics for turning the writer's draft into the reader's document - and the order you apply them in matters as much as the tactics themselves.
LiveThe six self-editing tactics3 min▶
Google's six tactics, translated into data-team reality:
- Adopt a style guide. Stop debating "log in" vs "login" per doc; the guide decides once. Our .vale.ini from Session 7 automates the checkable half.
- Think like your audience. Reopen docs/AUDIENCE.md and reread your draft as the new analyst. Where would that persona stop and DM you?
- Read it aloud. Your ear catches what your eye forgives: run-on sentences, three "howevers" in a row, a paragraph you can't finish in one breath.
- Come back later. Even an hour away resets your eyes. Overnight is better. The curse of knowledge from Session 1 fades a little with distance.
- Change the context. Print it, change the font, read it on your phone. A different rendering breaks the "I already know what this says" autopilot.
- Get a peer editor. This is exactly the doc review workflow from Session 7 - a reviewer who reads as the audience, not as a co-author.
LiveThe compounding checklist: seven sessions in one pass3 min▶
Everything this course taught is now an editing checklist. Run it top to bottom - big decisions first, mechanical polish last:
| Check | From | Ask |
|---|---|---|
| Audience match | Session 1 | Does every section serve someone in AUDIENCE.md, at their knowledge level? |
| Scope statements | Session 1 | Does the top declare what this covers, what it doesn't, and who it's for? |
| Quadrant purity | Session 5 | Is the how-to still a how-to, the reference still a reference - no tutorials leaking into lookup tables? |
| Structure | Session 3 | Lists where there are steps, tables where there are lookups, a lead sentence on every paragraph? |
| Sentence rules | Session 2 | Active voice, strong verbs, one idea per sentence, no "there is/there are" openers? |
Self-studyStyle guides as an editing shortcut2 min read▶
A style guide converts a hundred per-sentence judgment calls into zero. Adopt an existing one rather than writing your own: the Google developer documentation style guide and the Microsoft Writing Style Guide are both free, both excellent, and both opinionated enough to settle arguments.
- Adopt, then override sparingly. Our DOCS.md from Session 7 is one page of team-specific overrides on top of Google's guide - that's the right ratio.
- Automate the checkable half. Vale rules catch banned words and casing; humans keep judgment calls like tone and audience fit.
- Go deeper: Deep dive 4 covers building a team style guide and docs norms that survive contact with a real sprint.
Diagrams and sample code 5 min live
The two highest-trust elements in any doc are the diagram and the code block, because readers treat both as ground truth. Google's rules for each start in the same place: decide what the element must say before you build it, and never let it say more than one paragraph's worth.
LiveWrite the caption first, then draw2 min▶
Google's illustrating unit inverts the usual order: write the caption BEFORE you draw anything. The caption is the diagram's thesis sentence - if you can't write it, you don't know what the diagram is for yet. The figure above was built exactly this way: caption first ("Raw CSVs flow through three fixed steps to one metrics file"), boxes second.
- One paragraph per diagram. A diagram should carry no more information than one paragraph of prose. Big system? Draw the overview, then separate diagrams per subsystem - never one wall-chart with forty boxes.
- Direct the eye. Callouts and arrows tell readers where to look first. A diagram with no visual entry point makes every reader invent their own reading order.
- Instructive, not decorative. If deleting the graphic loses nothing, delete the graphic. Screenshots of logos and stock clip art teach zero.
LiveThe sample-code quality bar2 min▶
Readers copy-paste your code blocks into terminals and production. Google's bar: good samples are correct, concise, understandable, and reusable - in that priority order.
- Correct means tested. Every command in the Pulse README must build and run without errors, and produce the exact output the README shows. Session 7's link checker can't test this; you must.
- Production quality, language conventions. Readers copy your style along with your code. A sloppy sample teaches sloppiness with authority.
- Comments explain WHY, not what.
# sort by dateabove a sort is noise;# metrics.py assumes chronological inputis documentation. - Sequence simple to complex, and never trade correctness for brevity. A shorter sample that only works on happy-path input is a trap, not a kindness.
The README that drifted. A team's README showed python run.py --all; a refactor renamed the flag to --full and nobody updated the doc. For six months every new hire's first experience of the codebase was a stack trace. Untested sample code is worse than none - it fails with the reader's confidence at maximum.
Self-studyDiagram tools, and revising on feedback2 min read▶
Tooling matters less than the caption-first habit, but Google's shortlist is practical: Google Drawings, diagrams.net, and LucidChart all work; export to SVG so the diagram stays sharp at any zoom and diffs like text in a repo.
- Diagrams are drafts too. Show the diagram to one reader from the target audience and ask them to narrate it back. Where their narration stalls, revise - same loop as prose, same peer-editor tactic as Part 1.
- Keep the source file in the repo next to the export, so the next editor revises instead of redrawing from scratch.
LLMs in the writing loop 4 min live
Google's newest unit treats LLMs as a legitimate drafting and revision tool with one non-negotiable condition: you verify everything, every time. An LLM can compress your drafting hours; it can also invent a config key that never existed, in perfect confident prose.
LiveThe drafting recipe, and the iron rule2 min▶
A useful LLM drafting prompt has four parts, all of which you already have from this course:
- Role: "You are a technical writer on a data engineering team."
- Target audience: paste the relevant persona straight from docs/AUDIENCE.md - the Session 1 work pays off again.
- Doc type and style constraints: "a how-to guide; numbered steps; active voice; sentence-case headings; follow the Google developer style guide."
- Attached context: the actual code. Attach ingest.py, clean.py, metrics.py and config.yaml, not your memory of them.
Self-studyRevising with LLMs, and when to leave them out3 min read▶
For revision, Google's guidance mirrors the editing funnel: ask the LLM about organization BEFORE grammar. "Does this doc's structure serve a new analyst? What would you reorder or cut?" is a better first prompt than "fix my grammar" - the grammar pass is wasted on paragraphs the structure pass would delete.
- Good LLM jobs: reorganization proposals, summarizing a long doc into a scope statement, reformatting prose into a table, tightening wordy sentences - each one verified after.
- When NOT to use one: ADR context sections. An ADR records why a decision was made - the constraints, the options considered, the politics of the moment. The LLM wasn't in the room. It will produce a plausible context, and plausible-but-invented history is exactly what ADRs exist to prevent.
- Keep authorship. The LLM drafts; you decide. The name on the commit is accountable for every claim in the doc, including the generated ones.
The full editing pass on Pulse ★ 8 min · everyone follows
We run the Part 1 compounding checklist over the two most-read Pulse docs: README.md and docs/how-to-diagnose-low-day.md. Big to small, top to bottom.
Open README.md next to docs/AUDIENCE.md. Run checks in funnel order: audience match, scope statements, quadrant purity, structure, then sentences. Log every finding - do not fix anything yet.
Repeat for docs/how-to-diagnose-low-day.md, this time reading as the 2am on-call engineer. Read one section aloud - the ear test finds what the checklist misses.
Rank each doc's findings by reader damage. Fix the top 3 per doc, biggest first. Resist fixing typos before structure - that's polishing sentences that might not survive.
Commit with a message that says what the edit pass changed, e.g. docs: edit pass - front-load LOW triage decision, split run steps. The docs-as-code pipeline from Session 7 lints it on push.
Caption first: diagram the pipeline ★ 7 min · build your own
Pulse's README explains the run order in prose. Now we add the one diagram it deserves, using the caption-first method from Part 2 - and you check your sketch against the model answer already sitting on this page.
Write the caption before drawing anything: one sentence stating what the diagram must teach. Aim for something like "Raw CSVs flow through three fixed steps to one metrics file."
Sketch it - paper, diagrams.net, anything. Include only what the caption promises: the three scripts, the data between them, and config.yaml feeding all three. No infra, no future plans, no forty boxes.
Apply the one-paragraph cap: if your sketch says more than one paragraph of prose could, split it or cut it.
Compare against the Part 2 figure above - that SVG is the model answer for this exercise. Check: does your version have a visual entry point? Does every arrow mean the same thing?
Export to SVG, drop it in the repo, and reference it from the README under its caption.
The caption that killed a diagram. An engineer spent a day on a beautiful full-architecture diagram, then couldn't write its caption - it turned out to be four diagrams in a trench coat. The caption-first rule costs one sentence and saves the day of drawing.
Ship v1.0 and close the loop ★ 8 min · milestone 4
Time to ship. We cut the 1.0.0 changelog entry, tick every row of the Session 1 doc plan, and then run the ultimate acceptance test: Session 1's three newcomer questions, against the finished docs, on the clock.
Add the 1.0.0 entry to CHANGELOG.md (skeleton below), listing the complete doc set under Added.
Open docs/PLAN.md from Session 1 and tick every row: README (S4), how-to (S5), reference (S6), ADR-001 (S6), CHANGELOG (S6). Every planned doc exists and names its reader's action.
The acceptance test - answer Session 1's three newcomer questions using ONLY the docs: How do I run it, and in what order? Which event types are valid? What does the LOW alert mean? Target: under 60 seconds each.
Remember Session 1: those same answers took minutes of code archaeology through config.yaml and metrics.py. That delta is the value of everything you built in eight sessions.
The graduation assignment ◐ 2 weeks
- Pick ONE undocumented system at work - a pipeline, a service, a spreadsheet empire - and run the full 8-session loop on it in the next two weeks: audience + plan (S1), a rewritten core doc with clean sentences and structure (S2-S3), a README (S4), one how-to (S5), reference + ADR + changelog (S6), docs-as-code checks (S7), and this session's editing pass to ship it.
- Timebox it: the point is a shipped v1.0 doc set, not a perfect one. Three real docs that exist beat ten planned ones.
- Run the acceptance test from Demo 3 on your system: can a newcomer answer their three most likely questions from the docs alone, in under a minute each?
- Then go deeper with the deep dives, starting with writing helpful error messages - the most-read docs your systems will ever produce - and continuing through accessible writing, API docs, and style guides.
Official sources covered
This session completes Google's Technical Writing Two. What stays with the original: the facilitated in-class exercises and peer-editing workshop formats (facilitator guides are free).
Three questions before you go 🎯 ◐ 90 seconds
1 · You have 20 minutes to edit a draft. What do you check first?
Edit big to small. Structure decisions delete whole paragraphs - never polish a sentence that should be deleted. Typos and sentences come last.
2 · You're about to add a diagram to the README. What does the caption-first rule say to do?
The caption is the diagram's thesis. If you can't write it, you don't know what the diagram is for - and it caps the content at one paragraph's worth of information.
3 · An LLM drafts your config reference and includes a key called retry_limit that you don't recognize. You should...
The iron rule: verify every LLM output against the code. A hallucinated config key fails the reader who trusted your reference most - there is no "probably" and no "experimental" escape hatch.