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.
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)
