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
* 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 sentence = one idea
* Convert some long sentences to lists. Technical readers generally love lists. Seek opportunities to convert prose into lists. Format sequential steps as numbered lists.
* In the United States, reserve which for nonessential subordinate clauses, and use that for an essential subordinate clause that the sentence can't live without.
* If you read a sentence aloud and hear a pause just before the subordinate clause, then use which. If you don't hear a pause, use that. Place a comma before which; do not place a comma before that.
Python is an interpreted language, which Guido van Rossum invented.
FORTRAN is perfect for mathematical calculations that don't involve linear algebra.
* Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes zoom towards the table.
* The work of writing is simply this: untangling the dependencies among the parts of a topic, and presenting those parts in a logical stream that enables the reader to understand you.
* Good opening sentences establish the paragraph's central point. Effective opening sentences can take many forms. Starting a paragraph with a rhetorical question, for example, can engage readers.
* Focus each paragraph on a single topic
* Readers generally welcome paragraphs containing three to five sentences
* Good paragraphs answer the following three questions:
- What are you trying to tell your reader?
- Why is it important for the reader to know this?
- How should the reader use this knowledge. Alternatively, how should the reader know your point to be true?
* Good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills
* Writing to meet your audience's needs requires unselfish empathy.
* A good document begins by defining its scope. A better document additionally defines its non-scope
* Beyond the audience's role, a good audience declaration might also specify any prerequisite knowledge or experience.
* Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, page one of any long document is the hardest page to write. Therefore, be prepared to revise page one many times.
* Our company uses C++, Python, Java, and JavaScript.
The final comma, the one inserted between items N-1 and N, known as the serial comma or Oxford comma—is controversial. Consider circumventing the controversy by converting embedded lists into bulleted lists.
* A period separates distinct thoughts; a semicolon unites highly related thoughts. The thoughts preceding and following the semicolon must each be grammatically complete sentences
* An em-dash represents a longer pause—a bigger break—than a comma. For example:
Protocol Buffers—often nicknamed protobufs—encode structured data in an efficient yet extensible format.
* Use parentheses to hold minor points and digressions. Parentheses inform readers that the enclosed text isn't critical.
* Write in the second person. Refer to your audience as "you" rather than "we".
* Format code-related text as code font.
* Outline a persona for your audience. Think like your audience
* Just as engineers need peers to review their code, writers need editors to give them feedback on docs - some one familiar with the style guide you follow.
* Prefer task-based headings
* Focus the reader's attention through discontinuities.
* Write the caption before creating the illustration
* Avoid illustrations that require more than five bulleted items to explain.
* Callouts in pictures are often better than paragraph long explanations of the pictures
* Scalable Vector Graphics easily scale diagrams based on space constraints so that no matter the size, you end up with a high quality image.
* In tutorials, point out dragons. Provide not only examples but also anti-examples.
* 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 sentence = one idea
* Convert some long sentences to lists. Technical readers generally love lists. Seek opportunities to convert prose into lists. Format sequential steps as numbered lists.
* In the United States, reserve which for nonessential subordinate clauses, and use that for an essential subordinate clause that the sentence can't live without.
* If you read a sentence aloud and hear a pause just before the subordinate clause, then use which. If you don't hear a pause, use that. Place a comma before which; do not place a comma before that.
Python is an interpreted language, which Guido van Rossum invented.
FORTRAN is perfect for mathematical calculations that don't involve linear algebra.
* Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes zoom towards the table.
* The work of writing is simply this: untangling the dependencies among the parts of a topic, and presenting those parts in a logical stream that enables the reader to understand you.
* Good opening sentences establish the paragraph's central point. Effective opening sentences can take many forms. Starting a paragraph with a rhetorical question, for example, can engage readers.
* Focus each paragraph on a single topic
* Readers generally welcome paragraphs containing three to five sentences
* Good paragraphs answer the following three questions:
- What are you trying to tell your reader?
- Why is it important for the reader to know this?
- How should the reader use this knowledge. Alternatively, how should the reader know your point to be true?
* Good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills
* Writing to meet your audience's needs requires unselfish empathy.
* A good document begins by defining its scope. A better document additionally defines its non-scope
* Beyond the audience's role, a good audience declaration might also specify any prerequisite knowledge or experience.
* Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, page one of any long document is the hardest page to write. Therefore, be prepared to revise page one many times.
* Our company uses C++, Python, Java, and JavaScript.
The final comma, the one inserted between items N-1 and N, known as the serial comma or Oxford comma—is controversial. Consider circumventing the controversy by converting embedded lists into bulleted lists.
* A period separates distinct thoughts; a semicolon unites highly related thoughts. The thoughts preceding and following the semicolon must each be grammatically complete sentences
* An em-dash represents a longer pause—a bigger break—than a comma. For example:
Protocol Buffers—often nicknamed protobufs—encode structured data in an efficient yet extensible format.
* Use parentheses to hold minor points and digressions. Parentheses inform readers that the enclosed text isn't critical.
* Write in the second person. Refer to your audience as "you" rather than "we".
* Format code-related text as code font.
* Outline a persona for your audience. Think like your audience
* Just as engineers need peers to review their code, writers need editors to give them feedback on docs - some one familiar with the style guide you follow.
* Prefer task-based headings
* Focus the reader's attention through discontinuities.
* Write the caption before creating the illustration
* Avoid illustrations that require more than five bulleted items to explain.
* Callouts in pictures are often better than paragraph long explanations of the pictures
* Scalable Vector Graphics easily scale diagrams based on space constraints so that no matter the size, you end up with a high quality image.
* In tutorials, point out dragons. Provide not only examples but also anti-examples.
Comments
Post a Comment