Takeaways from Google's Technical Writing Course
Google has made available the same technical writing course that Google engineers also take. While the overall material is very useful, the following points appealed to me: * State key points at the start of each document. * Determine what your target audience already knows and what your target audience needs to learn. * Understand the curse of knowledge. * Break long topics into appropriate sections . * Prefer active voice to passive voice. Active voice is usually clearer & shorter. Active Voice Sentence = actor + verb + target Passive Voice Sentence = target + verb + actor Active: "He was born in 1980" Passive: "1980 was the year he was born in" * Adjectives and adverbs can make technical documentation sound dangerously like marketing material. Refactor amorphous adverbs and adjectives into objective numerical information . * Extra lines of documentation introduce additional points of failure. * Focus each sentence on a single idea. one ...