It is always preferable to design user interfaces that are so easy to learn that nobody will ever need the documentation. ... Even so, users sometimes do have to refer to help information. – J. Nielsen, Designing Web Usability, 2000
Nobody reads documentation. – M. Rettig, CACM, 34(7), 1991
  1. Technical Writing (read Sections 1 & 3–4):

    1. Compare and contrast technical and general communication.
    2. Be familiar with the range of genres associated with technical writing.
    3. Understand and be able to describe the importance of audience analysis, accuracy and document layout for technical writing.

    We also include internal documentation here, i.e., code comments, which we’re building using JSDoc format.

  2. Technical writing style (study Sections 7–19).

    1. Be able to describe, recognize and use the following grammatical constructions appropriately:
      1. active vs passive voice
      2. present, past vs future tense
      3. first, second vs third person
      4. articles
    2. Be able to describe, recognize and use the following stylistic features:
      1. sentence length
      2. sematic ambiguity
      3. application consistency
      4. action verbs
    3. Be able to compare and contrast the use ordered and unordered lists and to use the appropriate punctuation and consistent style for lists.
    4. Know how to apply the general principles stated in the section on “clarity”.
  3. I Won't Hire People Who Use Poor Grammar:

    1. Know how to avoid Wiens’s pet peeves: its / it’s; to / two / too; there / their / they’re; (and, I hasten to add, your / you’re)
    2. Know how to use/avoid the following constructions, referenced by Weins, appropriately:
      1. Sentence-ending prepositions
      2. Split infinitives
      3. Double negatives
    3. Does he have a valid point? Why or why not?
  4. Legibility, Readability, and Comprehension — Writing for the web is different from writing for smart phone apps, but there are many similarities. Be sure you understand Nielsen’s points on:

    1. His three basic criteria
    2. The Flesch-Kincaid reading score
    3. The inverted-pyramid writing style
  5. Re-read Postman’s article: “Five Things We Need to Know About Technological Change”, focusing on the fifth of his ideas.

    1. Briefly name Postman’s five ideas.
    2. Describe his fifth idea and explain whether or not you agree with him.