Google's Technical Writing Courses for Engineers
* [time=Sun, Apr 19, 2020 6:28 PM]
* Source: [Google's Technical Writing Courses for Engineers](https://developers.google.com/tech-writing/overview)
* ###### tags: `writing`
[Technical Writing One](https://developers.google.com/tech-writing/one/summary) covered the following basic lessons of technical writing:
- Use terms consistently.
- Avoid ambiguous pronouns.
- Prefer active voice to passive voice.
- Choose strong verbs.
- Pick specific verbs over vague ones.
- Focus each sentence on a single idea.
- Convert some long sentences to lists.
- Eliminate unneeded words.
- Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant.
- Keep list items parallel.
- Start numbered list items with imperative words.
- Introduce lists and tables appropriately.
- Create great opening sentences that establish a paragraph's central point.
- Focus each paragraph on a single topic.
- Determine what your audience needs to learn.
- Fit documentation to your audience.
- Establish your document's key points at the start of the document.
[Technical Writing Two](https://developers.google.com/tech-writing/two/summary) covered the following intermediate lessons of technical writing:
- Adopt a style guide.
- Think like your audience.
- Read documents out loud (to yourself).
- Return to documents well after you've written the draft.
- Find a good peer editor.
- Outline a document. Alternatively, write free form and then organize.
- Introduce a document's scope and any prerequisites.
- Prefer task-based headings.
- Disclose information progressively (in some situations).
- Consider writing the caption before creating the illustration.
- Constrain the amount of information in a single drawing.
- Focus the reader's attention through discontinuities.
- Create concise sample code that is easy to understand.
- Keep code comments short, but prefer clarity over brevity.
- Avoid writing comments about obvious code.
- Focus your commenting energy on anything non-intuitive in the code.
- Provide not only examples but also anti-examples.
- Provide code samples that demonstrate a range of complexity.
- Make a practice of continuous revision.
- Provide different documentation types for different categories of users.
- Compare and contrast with something that readers are already familiar with.
- In tutorials, reinforce concepts with examples.
- In tutorials, point out dragons.