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
-
Technical Writing
(read Sections 1 & 3–4):
- Compare and contrast technical and general communication.
- Be familiar with the range of genres associated with
technical writing.
- 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.
-
Technical writing
style
(study Sections 7–19).
- Be able to describe, recognize and use the following
grammatical
constructions appropriately:
- active vs. passive voice
- present, past vs. future
tense
- first, second vs. third
person
- articles
- Be able to describe, recognize and use the following
stylistic features:
- sentence length
- sematic ambiguity
- application consistency
- action verbs
- Be able to compare and contrast the use ordered and
unordered lists and to use the appropriate
punctuation and consistent style for lists.
- Know how to apply the general principles stated in the
section on “clarity”.
-
I Won't Hire People Who Use
Poor Grammar:
- Know how to avoid Wiens’s pet peeves: its /
it’s; to / two /
too; there / their /
they’re; (and, I’ll also add,
your / you’re)
- Know how to use/avoid the following constructions,
referenced by Weins, appropriately:
-
Sentence-ending
prepositions
- Split
infinitives
- Double
negatives
- Does he have a valid point? Why or why not?
-
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:
- His three basic criteria
- The Flesch-Kincaid reading score
- The inverted-pyramid writing style
-
Re-read Postman’s article:
“Five Things We Need
to Know About Technological
Change”, focusing on the fifth of his ideas.
- Briefly name Postman’s five ideas.
- Describe his fifth idea and explain whether or not you agree
with him.