TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Comeau Lisa,ComeauL -at- MOHYF-MX1 -dot- MOHDEV -dot- GOV -dot- ON -dot- CA,Internet writes:
>Any ideas on how to bombard the team with my ideas and hypnotize them into
agreeing- I mean, >any ideas on how to get my documentation point across and
improving customer service through >the written word?
CK:
Maybe this is a good time for me to introduce myself. I'm a former tech
writer (Lawrence Berkeley Lab) now teaching workplace writing in British
Columbia. In April, International Self-Counsel Press will bring out my book
Write for the Web. While it's aimed at Web-content developers (both
professional and amateur), many tech writers fill that role also, or contend
with very similar problems.
So what follows is an excerpt from Write for the Web. I hope parts of it, at
least, will be of use to Lisa and others here. (And thank you all, by the
way, for your very interesting posts--I'm learning a lot here!)
The Six Principles of Webwriting
You may intend your Website to be simply an electronic archive of writing
designed for print on paper. Or you may be using hypertext in experimental
ways for small audiences. In such cases, you can happily ignore the advice
that follows. Otherwise, whatever the purpose and content of your site, I
suggest that your text should reflect six basic principles.
1. The first principle we might call the Structure and Content Principle,
because it affects both the organization of your site and the text you put
into it. This principle has three elements:
*Orientation,
*Information,
*Action.
In a business letter, for example, you supply appropriate background
information and standard formatting (orientation) to help the reader make
sense of your main message (information) and to understand what should happen
as a result of that information (action). So you might explain that your
crowded warehouse is forcing you to offer widgets at unheard-of low prices,
and customers can act on that information by calling your 1-800 number.
Orientation on a Website should appear on the front page:
*what the site's about
*how it's organized
*how to navigate it.
The information is your text and graphic content, whether displayed on
several linked pages or one long, scrolling page.
The action is whatever you want your user to *do* as a result of absorbing
that information: e-mail you, provide a credit-card number, subscribe to a
listserv, click on the link to your advertisers. (Don't forget that since
many readers may first come to your site through one of your archived files,
orientation can be just as important on that file's page as on your front
page.)
Five other workplace-writing principles are also at work on the Web:
2. Webwriting should be understandable at first glance.
Let's call this the Clarity Principle. Your site should not be an IQ test. If
you baffle your readers with jargon or obscure language, they have every
right to go elsewhere. To keep them, try to be clear, coherent, and concrete.
Clarity means you should use direct and natural expression, neither too
casual nor too technical. Coherence is a real challenge if each page is a
chunk that has to stand on its own, without relying on information on other
pages. Concreteness means using words that readers can visualize easily: if
you're talking about Jersey cows, don't use relatively abstract words like
"livestock."
3. Webwriting should be the bare minimum solution to a problem.
This is the Simplicity Principle. Don't put anything on your site unless you
know it's unavailable elsewhere. If it is available on another site, just
provide a link with an explanatory blurb. When you do put something on your
site, it should be as short as possible. Yes, you can archive long articles,
even books-but don't archive more than you absolutely need to. A company may
have a good reason to archive each of its annual reports and news releases.
Authors might archive all their out-of-print books, just to make them
available again. A freelance consultant, however, probably needs to archive
only a few reports to give clients a positive impression.
4. Webwriting usually displays a positive attitude.
This is the Positive Principle. Even if your site is denouncing violations of
human rights or the destruction of the environment, you must think your users
can do something about those problems. Otherwise, why bother? So when you
present problems, suggested solutions should be close at hand.
5. Webwriting should present facts and ideas in terms of the reader's
advantage.
This is the You Principle. In business it's called the "you attitude"-making
sure that you talk about your reader more than you talk about yourself. So
instead of writing:
I've listed the top 15 companies I consider a threat to the environment
-you can write:
You can e-mail your protests to the top 15 environmental polluters
This is more than simple courtesy. Your readers have their own purposes for
coming to your site, and you are there to serve those purposes. To the extent
that you understand what your readers want, and you anticipate their needs,
your site will succeed and your readers will return.
6. Webwriting should display correctness and consideration.
This is the Professional Principle. But you don't have to be a doctor or a
lawyer to look professional--you just have to respect yourself, your readers
and your subject. Correctness means good organization and format (critical
for navigation), accurate names and addresses (critical for credibility and
for sales), good spelling and grammar, appropriate language and proper tone.
English errors distract from the message. If your content is serious (human
rights violations) but your tone is flippant or casual (These dictators are
jerks), you're sabotaging yourself.
Consideration means putting yourself in your readers' shoes. They are doing
you a favor by visiting your site, and you owe them a rewarding experience.
Will they stick around for that killer graphic to download if they've only
got a 14.4 modem? Will they really want to scroll through your list of the
hundred worst movies of all time? An out-of-date site with "link rot" (links
that go nowhere) wastes readers' time.
