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.