Post by Kerisblade on Sept 9, 2007 9:27:40 GMT -5
The remarkable growth of the information technology industry has created a tremendous demand for technical writers – people who translate computer engineer’s notes into common language. The pay is pretty good considering how little work they actually do.
For this category of IT facilitators, the goal is to make their work appear as difficult as possible so as to strengthen the notion of their indispensability. This practically guarantees them cushy jobs and long-term prospects for the future.
What’s the use of rendering technical documents into plain English that any Tom, thingy or Harry could write? Doing so would see the computer industry wising up and hiring the Toms, thingys and Harries at half the pay and none of the perks.
So if you are an aspiring technical writer, you're guaranteed success in the field if you can make running Scandisk sound like you've built a new supercomputer from Home Depot supplies. But not everyone is lucky enough to have that kind of talent, so use the following pointers to at least get you by and keep those fat paychecks coming.
Lesson One: Style
Acronyms
All abbreviations are called acronyms. Don't let anyone tell you differently. Anyone who tries to argue this point is just being pedantic. Blow them off. Any term with at least two words must be assigned an acronym, and it must be defined in parenthesis, even if you'll never use the term again. Don't worry if you've already used an acronym for something else—the readers will know what you mean.
Remind your readers what an acronym stands for at random intervals. If you're not sure how often you should insert these reminders, just define the acronym every time you use it. Here is the correct way to take advantage of acronyms:
It is in the best interests of the United States (U.S.) of America (USA) to develop a Tax Plan (TP) that punishes neither America's Disadvantaged Working Class (ADWC) nor the Independently Wealthy (IW). It should come as no surprise that both the ADWC and IW would like to see a Tax Plan (TP) that includes Lower Tax Rates (LTR), but the demand for LTR must be balanced against the needs of the Taxpaying Public (TP). As a result, the current TP should be eliminated.
Colloquialisms
Avoid using common phrases in technical documents. They will confuse the reader. If using a colloquialism is absolutely unavoidable, set it out in quote marks, then define it for good measure. That way you can make sure you are belabouring the point, like a good technical writer should. Here is an example of how to use a colloquialism:
It was raining "cats and dogs" (i.e., it was raining so hard that it seemed almost as if domesticated animals (e.g., cats and dogs) were falling from the sky rather than raindrops).
Numbers
Be all-inclusive. Write out all numbers, then follow with numerals in parenthesis. You do not want to exclude anyone who understands one notation but not the other. Example:
I own fourteen (14) cats.
Lesson Two: Grammar
Commas
Commas are a sign of weakness. Good sentences are clear without the use of commas. Bad sentences use commas as a crutch to help readers limp along. Rewrite any sentence that requires the use of a comma.
If all else fails just take the commas out of the sentence without changing anything else. Occasionally sprinkle a few commas into the document at random just to keep the English-major weenies happy.
Passive Voice
You're better off with passive voice. Active voice annoyingly insists on placing attribution to actions, and we all know that sooner or later somebody's going to get fired for being attributed to something.
English-major weenies like to insist that passive voice is bad, but that's because they have no real authority and therefore are in no great danger of getting fired for anything. Put them in management and see how quickly they adopt passive voice.
Semicolons
This is the Mystery Punctuation. No one can use this properly, not even the English-major weenies. But semicolons make a sentence look impressive, so use one in place of a comma every now and then (that is, if you still use commas; see "commas").
Lesson Three: Technical Terms
Functionality
There are two ways to use this versatile word. The first is to use it in place of a word like "function" or "feature". Those words are overused, so functionality will make your document seem fresh by comparison: Do you have the power windows functionality on your car?
The second way is to use it as an indicator of general operation. For example, instead of writing: The intern broke the copier. Try writing:
The functionality of the copy machine has been compromised by our Associate Coffee/Errand Assistant I.
Impact
This is a wonderful word. Use it as much as possible! Any time you have an opportunity to explain that an action causes something to happen, be sure that it was an impact (you can use it as a verb, too, by explaining how an action impacted something).
Never write: Turn the computer on. When you could write: Utilize the power on/off interface, located on the forward-face of the Advanced Digital Data Storage System (ADDSS) when installed in the standard configuration (see Appendix A), to impact the operational status of the ADDSS System.
Well, good luck in your new job and remember, you’re assured of a rosy future as long as you remember to make the easy appear so difficult, no one else can do your job.
Extracted from the Manual for Would-Be Techie Writers