Aphorisms

[David Orr <dorr -at- ORRNET -dot- com>]

I've always liked knowledge encapsulated in aphorisms because they are easy
to remember. Here are a few about tech writing I've developed for myself or
stolen. I'd be interested in reading others developed by members of the
list. Maybe the topic title should be "Private Wisdom." 

Documentation is a sign of deficiencies in product design.
Give user 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 Orr
Orr & Associates Corporation
http://www.orrnet.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 
Conference East, June 4-5, Baltimore/Washington D.C. area.
http://www.pdfconference.com or toll-free 877/278-2131. 

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.