|
September, 2005 |
Top Ten Things I Wish I’d Known Sooner: Technical Writing BasicsWhen I started out as a new technical writer, the unwritten basic rules seemed pretty straightforward:
While these rules are a good starting point, I quickly learned that they were not enough. After many years, jobs, co-workers, and manuals, I realized that there were additional basics that, once pointed out, made me say "Of course, it's so obvious; gee, I wish I'd realized that sooner." This article lists those things. So, in no particular order, here is my "top ten list" of the things I wish I’d known earlier in my career. We Don’t Write Science FictionTechnical writers write facts; we don't make things up. If you don't know how something works, ask those who do, such as the engineers, technical support, or end users. More importantly, verify that things work the way you say they do whenever possible. Note Updated FeaturesWhen updating a manual, include a list of changes for previous users—new/changed function names, keyboard commands, and new terms. You don't have to define them there, but references help users find the information quickly. Write Intelligently, but Not ObtuselyDon't show off your expansive vocabulary—or that you own a thesaurus. If readers cannot understand your writing, they'll skip it. Worse, when you use the wrong term, they will wonder what else is incorrect in the manual. Be technically accurate without being confusing. Late Editing Is a Luxury—So Edit As You GoEven if you look at the chapter only a few hours later or first thing the next morning, edit your work. Mistakes occur more frequently when editing to meet a deadline. Know Your Information ResourcesDon't go to the engineers or customer support only when you need something. You don't have to be buddies, but being acquaintances and checking in sporadically helps the relationship. A Picture Is Worth a Thousand Words—If It’s the Right PictureUse screen shots if they help explain what you're trying to convey. Don't add screen shots "just because"; each picture must serve a specific purpose—either helping a user go from step to step or explaining a new procedure. A Style Guide Is Not Written in StoneA style guide is a living document—if an exception needs to be made, consult the group and, if necessary, update the style guide. Use the Documents YourselfUse the index to see if you can find information; if you can't, chances are a user cannot either. Look at the document as a user would: are the pictures clear, are step-by-step instructions accurate, and is the document easy to use? Take Your Job SeriouslyDon't belittle your job. If you do, others will too and the respect for you and your group will decrease. There Is Always an Opportunity to LearnWhether it is HTML, online help, XML, or something about the company, do not stop learning. Don't rely on the company paying for classes or teaching you. Go out and learn it on your own. You may be able to change careers or become the department expert on something, such as web page creation or editing. To Sum UpOur goal as professionals is to provide information of value to our audience. If experience is the best teacher, then perhaps these additional basics will be of value to both new and seasoned technical writers.
This article originally appeared in the September 2004 issue of Devil Mountain Views, the newsletter of the East Bay Chapter of the STC.
|
|||
|
Top Ten Things I Wish I’d Known Sooner: Technical Writing Basics |
||||
|
To be removed from this distribution list, please send us an e-mail with the word UNSUBSCRIBE in the subject line.
|
||||
