What Google Taught Me About Technical Writing

This article is a translated summary of a Google technical writing course, offering concrete advice for creating clear and effective documentation. It begins by introducing basic grammatical concepts such as nouns, pronouns, adjectives, verbs, and adverbs, and explains why precise pronoun usage prevents reader confusion.

Clear Writing – Emphasizes that the primary goal of technical writing is clarity. Examples show ambiguous pronoun references (e.g., "C++ is an old language, JavaScript is also old, but I still like this language") and how to replace vague pronouns with explicit nouns.

Concise Writing – Highlights the importance of brevity, comparing long sentences to code that is hard to read and maintain. It lists benefits of short code and sentences: easier reading, maintenance, and reduced error risk.

Active Voice – Demonstrates the structure of subject‑verb‑object sentences and contrasts active with passive constructions. Active voice is presented as more direct, familiar, and often shorter, improving comprehension.

General Writing Techniques – Covers sentence‑level advice (single‑idea sentences, avoid filler phrases), paragraph structure (clear opening stating what, why, and how), and the use of lists to break complex information into digestible points. It advises choosing the appropriate list type (ordered vs. unordered) and maintaining consistency in punctuation, logic, and capitalization.

Jargon and Context – Recommends minimizing domain‑specific jargon and explaining necessary terms, warning against the "curse of knowledge" where writers assume readers share their expertise.

Word Choice – Suggests using simple, common English words, especially for non‑native speakers, and avoiding overly ornate language that can make technical writing sound like marketing copy.

Meta‑Information – Advises providing an introductory overview, tailoring tone to the audience (e.g., dev.to vs. freeCodeCamp), and considering the reader’s background to ensure accessibility.

Conclusion – The author reflects on the valuable principles learned, encouraging readers to apply these guidelines to improve their own technical documentation.