Re: tech writing tips

Subject: Re: tech writing tips
From: Chuck Martin <techwriter -at- VNET -dot- IBM -dot- COM>
Date: Wed, 6 Apr 1994 17:11:43 PDT

There are tons, many that are learned not only through years of education,
but years of practice. At the risk of being too simple, here's a few off
the top of my head. I'm sure the other contributors will offer many more.

Keep It Simple. (Yes, there's one more "S" there.....). But it means
direct and to the point. Long words and technobabble aren't helpful when
you're users want to *do* something. Primarily because long, complex
terminology often (I could have said "frequently") is translated into
simpler terms by the reader. That translation takes time and (mental)
effort. So it's easier to be direct in the first place.

Put yourself in your user's/reader's place. What will you readers
want to do?

Good User's Guides are generally "task oriented." That means that, before
you start outlining and writing, you will want to identify the tasks
your users will perform. Then group them logically and present them
clearly.

Think like a user.

Make the information in your books easy to access. That means headings
that are descriptive, organization that is logical, and an index that is
complete. Indexes are especially important, and are one of the hardest
things to do right (I could have said "properly").

Pretend you're a user. (There's a trend here.)

A lot of books are available. Here are a few from my library at work.
Some were textbooks from my technical writing courses, others I bought.
I'm hesitant to recommend any because defferent presentations work
better for different people.

"How to Write a Computer Manual - A Handbook of Software Documentation,"
by Jonathan Price, Benjamin/Cimmings, 1984 (This was written by the folks
at Apple, who have pioneered many ways of presenting information.)

"Introduction to Technical Writing - Process and Practice," by Lois
Johnson Rew, St. Martin's Press, 1989

"Technical Writing - A Reader-Centered Approach," by Paul V. Anderson,
Harcourt Brace Jovanovich, 1991

"How to Write & Present Technical Information," by Charles H. Sides,
Oryx Press, 1991 (A smaller book)

"Handbook of Technical Writing," Brusaw, Alred, & Oliu, St. Martin's
Press, 1987 (More of a reference)

"Style - Ten Lessons in Clarity & Grace," by Joseph M Williams, Scott,
Foresman, & Co., 1989 (Am excellent book on writing clearly--with thanks
to my Style in Technical Writing instructor: Jan Spyridakis)

"Designing, Writing & Producing Computer Documentation," Denton &
Kelly, McGraw-Hill, 1993

There are plenty more. Best of luck.

Chuck Martin
Information Developer, IBM
techwriter -at- vnet -dot- ibm -dot- com

P.S. Remeber those users/readers. They're people too.


Previous by Author: Re: Online Help
Next by Author: Re: Windows Style guide
Previous by Thread: Tech Writing Tips
Next by Thread: Re: tech writing tips


What this post helpful? Share it with friends and colleagues:


Sponsored Ads