Orr's Aphorisms About Tech Writing
Contributed to our class by Dr. Christine Abbott
Dr. Abbott’s note:
David Orr (one of our Institute instructors and the founder of the first usability lab in Chicago) has given me permission to pass along these gems. Great advice and observations here!
David Orr:
FYI. Here are some aphorisms I've developed for myself or stolen:
Documentation is a sign of deficiencies in product design.
Give the user a contact point with product immediately.
Documenting the 20% of tasks that people have to use 80% of the time is more effective with new users than documenting all the tasks.
Identify six or seven critical functions to go in the Quick Start Guide.
Prototype documents should be generated early, iterated, and expanded into final documents. Client and user reviews should occur at each iteration.
Get something in front of them fast. Change it fast.
Greatest enemy of the good is the perfect.
User feedback is the killing field of cherished notions.
Users are everything: get user feedback early and often.
Graphic flow-chart overviews with screen captures in PowerPoint are a powerful way to give the BIG Picture.
Communication of the metaphor and the way of working through system are critical.
Train, train, train so the writer can do it right the first time.
Use templates with extensive Autotext and macros to automate standards and, thus, do it right the first time.
Quick Start Guides, either printed or online, are critical to giving the user a contact point with the product immediately.
Why editing sucks: it represents defect correction after the fact. If the writer has been trained thoroughly, has properly researched the audience and tasks, and uses templates and style sheets properly, he/she can do it right the first time and avoid the need for most editing.
Tutorials are effective for blank-slate applications like drawing programs, word processors, and spreadsheets.
Planning and process aren't ends in themselves, but they are important, especially to teamwork.
Involve users and clients in development to get ownership. You can sometimes mentor users into doing the writing and shorten a development process because of their superior knowledge of the job, product, and environment.
Clients don't care about process, just results. Process is, nevertheless, important to teamwork.
Don't rescue clients or teammates. No good deed goes unpunished. People begin to expect to be rescued, in fact plan on it.
Decentralize/coordinate rather than centralize/control.
Mentor, mentor, mentor junior people.
Delegate juicy things, not just unpalatable things, to subordinates to keep their enthusiasm high.
Some people start with the big picture; some people start with the details. Either way is OK.
Some people move very fast in a certain direction and change course very fast if the direction is wrong. Others don't move until they have researched and planned carefully to choose the right path. Both ways work, and often the two types of people get to the same place at about the same time.
Different people have different learning styles. Good documentation accommodates different learning styles.
Documentation is only part of a solution that might include, user interface, training, job aids, online help, Web sites, compensation changes, culture changes, and policy changes.
Decision tables/charts are useful, especially in non-linear situations.
Cross-departmental, cross-functional is best. There are often unacknowledged disconnects between how people are supposed to use a system and how they actually use it.
Quick and dirty process mapping and conceptual design can be done with sticky notes, magic markers, and butcher paper tacked on a wall.
Include concrete examples of abstract or complicated processes.
Use just the right amount of pictures. If three pictures are good, that doesn't mean fifty are automatically good. No picture is usually not good.
Users expect a new product to operate somewhat like an old product of the same type.
Often it's useful to show samples of effects you can get with a product, and then give directions for getting those effects.
No silver bullet. One size does not fit all. There is no one approach to documentation and training that works every time.
Stylesheets are essential, but better learned through training than editing. Stylesheets and standards should be built into the writer's head and into templates.
Eliminate the creative element in mechanical processes; stress it in design.
Many misunderstandings come from mistaking degree with kind. For example, writers often argue over the importance of having in-depth technical knowledge, versus writing and design ability. These are two different kinds of things; both are important. The real argument is over the degree of technical knowledge necessary in a particular environment to get the writing job done.
Marketing people and IDs have much to teach tech writers about design and audience. Tech writers have much to teach IDs about writing.
Psychological projection, insecurity, and blaming are the enemies of teamwork and progress.
Writers can only be pushed so far. Extreme hours beyond two weeks decrease productivity.
Burnout can be fatal to a writer's career. The only cure is sleep, exercise, and time off.
Confront now or fight later.
Best-case scenarios work out 0.5 % of the time. Managers who rely on them are headed for trouble.
You need to tell readers where you're headed-concisely-before launching into a long chain of reasoning. Often a graphic is best to do this. Otherwise, why should they invest the time if they don't know where you're headed?
Graphics must always have a cognitive purpose, not merely a decorative one.
Graphics and fonts are for emphasis-too many ruin the effect.
Sentence flow is more important than arbitrary shortness, but shortness is usually a good thing.
Readers' eyes glaze over at huge expanses of print.
Call-outs increase the value of illustrations by 100% or more.
Use document structure to layer information for different audiences. This includes hypertexting in online documents.
The main purpose of using active voice is to establish responsibility for an action.
The main purpose of using present tense is to avoid the confusion that multiple tenses can cause.
The eye is drawn first to the area containing the greatest mass of high contrast of light and dark on a screen or page. This is the principle behind headings and most graphical elements on a page or screen.
The eye of people in Western Civilizations goes left to right, top to bottom on a screen or page.
The most important question for a technical writer while writing is "What does the user need to know right NOW?"
A good procedure has an introduction, a picture or two, and numbered steps.
Miller's Magic Number-no more than 7 +/- 2 items in a list-is not perfect all the time, but it's pretty good most of the time.
Once you start writing, just crank it out. Avoid distractions and anything that halts writing.
A long-term to-do list can keep writing going by giving the writer a quick place to stash ideas that occur while writing. The idea is saved, but the writer can quickly continue writing.
M. David OrrOrr & Associates Corporation
Back to English 308 home page