Users Don't Want Good Editing, They Want Answers February
Synopsis: Usability starts with the words
on the screen, as did my entry to the field, coming from techwriting.
my strong advice below, to new techwriters and old, to stop
worrying about making techwriting valuable and instead
concentrate on making valuable techwriting.
A recent thread on the popular techwriting discussion group,
focused on the perennial techwriters' lament, how to convince
the business world that we techwriters do valuable work... that
we shouldn't be second-class citizens, that you can't outsource
us to another corner of the world, that we should be paid just
as much as developers, and so on.
My advice is to focus one's energies elsewhere. My comments
refer to business software techwriting in general, and I
To substantiate that these are not empty words... In ten years
I made it to the very top of the STC salary survey range even
though my credentials are entirely home-spun. And I also wrote
book that has sold 8000 copies.
So I've figured out a thing or two about writing. Or more likely,
about what readers want and need. With that preamble...
How to Convince People About the Value
- Stop worrying about making techwriting valuable and
instead concentrate on making valuable techwriting. For
enough to remember, this is the Charlie the Tuna rule.
- People don't want good editing. They want answers.
techwriting is all about research. If the only option,
the one of last resort, is pestering people for info, then
- Writing is for reading. Only your readers "own" the
My classic pet-peeve example is "E.E.Cummings".
Despite his preference for any damn capitalization he likes—and
I don't begrudge him, I just ignore him in deference to my
readers—capitalize things so that readers can read
your sentences. And don't be afraid to put a period outside
marks if it reduces misinterpretation. (Two or three issues
ago in the STC quarterly, someone wrote a beautiful article
debunking some grammatical traditions and dogmas. Could someone
help me with the citation?)
- Do less writing and more picture drawing.
only recently that my professional career can be reduced
to a single
cliche: a picture is worth 1000 words. It has nothing to
do with reader laziness: we are all incredibly overloaded
new info demands. Make posters, brochures, diagrams, reference
cards, cue cards, and hyperlinked flowcharts.
You will be valued long before genuine results are proven
or disproven, but that is the unfortunate hypocrisy of the
of techwriting. It has dominated book publishing for 1500
judges books by their covers—so if you think you are
going to reverse this, you are, um... mistaken.
- Get your techwriting placed right into the applications.
This is called usability and UI design.
This is the inevitable
evolution of software and the real place for good writing.
The recently lauded wave of Sarbanes-Oxley "pseudo work" (following
on the heels of IS0 9000 [and look how well that improved
software!]) is great if it helps some folks pay the rent,
but it is a
proposition overall; long-term, beauracracy doesn't create
wealth, it removes it. If you ride the S-O wave, don't cry
when the trough hits.
- Make all information accessible anywhere/anytime, what
I call profuse Help.
Put all of your product information into an integrated, web
accessible system. For sensitive information, use passwords,
not secreted-away information. Only format for paper approximately
40-70 pages per audience, what I call a "read-through." See
converted web page with my long-ago published STC article,
"To Print or Not to Print, What Should Go Online?"
- Base your writing priorities on those
layed out by Gary Blake in The Wall Street Journal, 1/7/97: "It Is Recommended
that You Write Clearly":
From http://www.engl.niu.edu/wac/fhndbk.html (just
a synopsis, if you find the full text, email
Blake (1995), an expert on business writing, has ranked
on a scale from one to ten. He notes that minor problems
may only cause embarrassment, whereas major problems in your
writing (6–10) could "seriously harm the health
of your organization" (p. A18). Spelling, punctuation,
and misused words may just embarrass you, but lengthy
sentences and paragraphs, passive language, vagueness,
and poor organization
could actually harm your professional reputation and
that of your firm. In the field of finance, the ability
concisely, and coherently is more than a virtue: it's
If you do all these things and are not valued, you know what
to do, right? Except for the rarest of employers, the way our
job market works, it is easier to make big steps by moving