Sentences that work

Google's rule is short: use terminology consistently. If you name something "the staged data" in paragraph one, it stays "the staged data" for the rest of the doc - not "the validated rows", not "the intermediate output". Synonyms feel like good style; to the reader they read as new concepts.

• New or unfamiliar term? Either link to a good existing definition, or define it yourself the first time it appears. Never make the reader infer a definition from usage.
• Pick official terms early. For Pulse we lock three today: staged (output of ingest.py), cleaned (output of clean.py), metrics (output of metrics.py). Every later doc uses exactly these.
• Elegant variation is for novels. In fiction, repeating a word is clumsy. In technical writing, repeating the term is the feature - repetition is how the reader knows it's the same thing.

Pronouns are pointers, and like pointers they dangle. Google's guidance: keep a pronoun within about five words of the noun it stands for, and if anything ambiguous could grab the reference, repeat the noun instead.

• The ~5 word rule. "Run clean.py after ingest.py finishes; it dedups the rows" - which script is "it"? Two nouns are in range, so the pronoun wobbles. Write "clean.py dedups the rows".
• Watch it, they, this, that. These four cause most of the damage. "This is important" - what is? Google's fix: put a noun after this or that ("this filter step is important").
• When in doubt, repeat the noun. Repeating "clean.py" three times in a paragraph costs nothing. One ambiguous "it" costs a re-read, or worse, a wrong command at 2am.

Google's acronym rules are more restrictive than most people expect, and they save readers real effort:

• On first use, spell out the full term in bold with the acronym in parentheses: "directed acyclic graph (DAG)". After that, use only the acronym - do not flip between the two.
• Only introduce an acronym at all if it is significantly shorter than the full term AND appears many times in the doc. An acronym used twice is a puzzle, not a shortcut - just write the words.
• Remember the cost model. Every acronym makes the reader run a tiny mental lookup on each occurrence. Familiar ones (CSV, API) are free for your audience; team-invented ones (PMDQ, the "pipeline metrics daily quality" job) are not.

You don't need grammar school to find passive voice - you need one pattern. Passive verbs are a form of be (is, are, was, were, been, being) plus a past participle (usually a verb ending in -ed or -en). Find that pattern, and you've found a sentence hiding its actor.

Notice what the active versions add for free: the actor. In pipeline docs the actor is usually a specific script, and naming it answers the reader's next question ("which script do I look at?") before they ask it. Active is also shorter - the passive tax is roughly two words per sentence, forever.

Google draws the analogy explicitly: shorter code is more maintainable, and so are shorter sentences. Each sentence should carry exactly one idea; when a sentence carries a list of things, convert it into an actual list (Session 3 goes deep on lists).

• The comma-and test. Every ", and" in a long sentence is a candidate cut point. "ingest.py validates headers, and it drops bad rows, and it writes staged output" is three sentences wearing a trench coat.
• Strong, specific verbs. "Occurs", "happens", "is done" are verb-shaped placeholders. "The dedup happens in clean.py" tells you less than "clean.py dedups rows on event_id" in the same breath. Weak verb + noun ("performs validation of") is one strong verb ("validates") in disguise.
• Reduce "there is / there are". These openers bury the real subject. "There is a threshold that flags low days" becomes "metrics.py flags days below the threshold". The sentence starts doing work two words sooner.
• Vague adjectives are unpaid promises. "Very fast", "quite large", "significantly better" - replace with the number. "Drops about 3% of rows" beats "drops some rows" in every audience.
• That vs which, the US convention: that introduces a clause the sentence needs (restrictive, no comma); which plus a comma adds an aside the sentence survives without (nonrestrictive). "Rows that lack event_id are dropped" vs "config.yaml, which lives in the repo root, holds the settings."

Microsoft's Top 10 tips arrive at the same place as Google from the product-writing side, and their before/after pairs are worth memorizing verbatim:

• "Use bigger ideas, fewer words." Their example: "If you're ready to purchase Office 365 for your organization, contact your Microsoft account representative." becomes "Ready to buy? Contact us." Same decision enabled, 80% fewer words.
• "Write like you speak." Read your sentence aloud; if you'd never say it to a colleague at their desk, rewrite it until you would. Contractions are welcome - "don't" reads faster than "do not".
• "Revise weak writing." Three concrete moves: start sentences with a verb where you can, cut "you can" openers, and avoid "there is / there are / there were". Their example: "You can access Office apps across your devices..." becomes "Store files online, access them from all your devices, and share them with coworkers." Every clause now starts with the action.
• The shared consensus. Where Google and Microsoft agree, treat it as law: second person "you", active voice, present tense (avoid "will" for things that simply happen), US spelling, no unexplained jargon.