Top Ten Things I Wish I'd Known Sooner

Newsletter of the East Bay Chapter of STC September/October 2004\| Home	Top Ten Things I Wish I’d Known Sooner: Technical Writing Basics

	by Dara Golden DMV Contributing Editor Dara Golden is the former Interim Editor of Connection, the Silicon Valley Chapter’s newsletter.
	When I started out as a new technical writer, the unwritten basic rules seemed pretty straightforward: meet your deadlines write accurately and clearly know the key contact people for your project 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 Fiction Technical 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 Features When 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 Obtusely Don'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 Go Even 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 Resources Don'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 Picture Use 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 Stone A 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 Yourself Use 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 Seriously Don'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 Learn Whether 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 Up	Our 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.

DMV Home \| EBSTC \| STC \| Contact Us Top Ten Things I Wish I'd Known Sooner \| Sharing Outreach More Effectively with Teachers Confessions of an STC Conference Groupie \| Member Spotlight \| Infinit(iv)e Possibilities \| Keeping Our Archive Updated Editor's Message \| President's Message \| Meeting Information \| Meeting Report \| New Members \| Networking Director's Report \| Society News \| Employment News \| Web Site Review Archives \| About DMV \| Sponsors