Great Technical Writing: The Two-Edged Sword of Reader Experience
Overview
When we write User Documents we rely on our Reader's/User's experience to simplify our work. This can cause problems for the Reader. This article will discuss the effects of Reader experience and how to minimize the negative effects of incompatible experience, and how to handle the writer's assumptions about the Reader.
Writer's Benefits: Relying on Reader Experience
When we write, we rely on our Reader's experience to give us a "starting point" for our User Document. Often we make hidden assumptions about our Reader's experience.
Here are some examples where relying on our Reader's experience makes things easy (and causes problems) for us as writers:
Example: Using a Computer's Mouse
In writing User Documentation for Graphical User Interface-based computer products (such as the Windows or Mac User interface), we assume that the the Reader knows how to use a mouse to click on items, drag, etc. This saves much background writing.
Example: Cooking: How to Measure Ingredients; Terms
Cook books save space by (usually correctly) assuming that a Reader can perform basic cooking operations (such as measuring ingredients), and terms (such as puree or slice).
Example: Common Acronyms
We rely on "common" acronyms such as AM and PM to simplify our writing lives. However, many Readers use a 24 hour clock, and thus AM and PM are meaningless to them.
Beware of any acronyms that you assume that your Reader knows. It is best to define acronyms in line (perhaps in parentheses) when they are first presented in that part of the User Document.
You cannot define them only the first time they appear in the User Document. This assumes incorrectly that Users read your User Document from start to finish.
Problems Writers Cause When Assuming User Experience
Our assumptions as writers can get us into trouble.
Example: Unfamiliar Words
Here's a gardening example: Acme's (a fictitious company) Illustrated Guide to Gardening in Canada (1979) makes an incorrect assumption about its Readers:
In one of their definitions they use a term, "the axil of a leaf" to define another term. "Axil of a leaf" is not listed in the book