Summary of Technical Writing Two

Technical Writing Two 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 on the relevant part of a picture or diagram by describing the takeaway in the caption or by adding a visual cue to the picture.
  • 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, note problems that readers may encounter.

Congratulations! You've completed the pre-class portion of Technical Writing Two.

The in-class component of Technical Writing Two helps you practice technical writing principles:

  • If your organization offers the in-class portion of Technical Writing Two, you are now ready for that class.
  • If your organization doesn't offer the in-class portion of Technical Writing Two, consider joining one of the free public courses listed on the Announcements page.