Chapter 12: Getting the Language Right By: Pair 9 Derek Wingert & Brock Delia-Shea

Write about actions, not functions Use the active voice: subject, verb, object Keep it simple Use parallel structure: group related information logically Provide helpful and informative overviews

It conveys the significance and meaning of the content It works with the user’s specific content and motivation It satisfies the user’s needs It’s written in an expected, human way It fits in our limited memories so words can be connected to meanings It uses familiar and logical patterns to make information more expected

Acronyms and abbreviations I would LOL if someone didn’t know this abbrev., but it could still happen (ROFL). Synonyms Using synonyms should be considered a petty crime. Avoid misdemeanors by using the same word(s). Long paragraphs and sentences The purpose of paragraphs is not to convey steps. First, you should list steps separately. Second, paragraphs should be short. Third, sentences should be kept to reasonable length because long sentences can become very tedious to read, and distract from the point that is trying to be make, since they just keep going on, and on, and on, much like this sentence is doing.

Emphasizing the Computer instead of the Program Enter the information into the computer. Don’t waste your money on the program – it’s obviously not needed. No connection between headings and topic I like rubber duckies. They make fun noise, and can be used to shoot water at other people. Tone is too formal or robotic This is bad. Use of the passive voice can deter readers. Use of humor Like we’d ever do that…

Task names are unclear Putting fingers to keyboard, this combination of words allows readers to determine what is being communicated. Steps that are not steps Read this step. Then read this one. You are getting the point. Read one more step (this one). Missing articles Boy once told me about teacher who did this.

Finally, a clear, concise chapter that made perfect sense. We were happy to be assigned this chapter, as it is applicable in more than just software documentation, and can be applied immediately. Questions?