The Tech Writer's Style Guide
The O Pine




We recommend Internet Explorer set to 1024x768.

© 2001 Brian F. Schreurs
Even we have a disclaimer.

Possessing similarities to consumables preprocessed by bovine livestock lifeforms.
The remarkable growth of the information technology industry has created a tremendous opportunity for people with skill putting words on paper. Technical writers, once a rare and highly skilled position, are now as common as fruit flies -- though they take up a lot more space. Yet the pay is pretty good considering how little work they actually do, so young English-major weenies desperate for employment continue to swarm around IT companies, hoping for a bit of rotting fru-- er, looking for a plum position.

But it's not quite as easy as pulling up a keyboard and translating an engineer's notes into common English. Because, you see, technical documents aren't written for people who use common English (no matter who the end user may be). No, they're written for your boss, who invariably is an engineer. And engineers like their documents to sound intelligent, and their idea of intelligent is to use big words.

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.

Bulleted Lists
There is simply no way to include too many bulleted lists. Bulleted lists make everything clear, because it takes a complicated sentence with too many commas and turns it into a simple and precise enumeration of critical points. Use as many bulleted lists as possible, because the more often you use them, the more clear your document becomes. Example:

My dear Elizabeth,
  • The weather is beautiful; and,
  • I wish you were here.
Love always, Angus

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 be sure your readers understand what you're trying to say. 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.

Hyphens
There are three different types, but only an English-major weenie can tell them apart. The only one you need to know about is the simple - . In a pinch, you can use two of them run together, like this: -- . Sometimes compound nouns need to be hyphenated and sometimes they don't, but nobody else knows when to do it either so just do it at random.

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

Summary

Now that you've had the opportunity to digest some pointers, it's time to give technical writing a try. The easiest way to start is to take a piece of text and rewrite it in proper technical writing format. Use this rewrite of Litte Red Riding Hood as a guide.

Little Red Riding Hood

At a previous but undetermined timeframe, a single-family domestic domicile was inhabited by a young girl, known as Little Red Riding Hood (LRRH), and her Maternal Parent (MP). The Maternal Parent (MP) had once provided for the fabrication of an article of clothing, a cloak in nature (including a "hood" or protective covering for the head of the wearer), that was RGB code [255,0,0] in hue (aka, "red"). As a result of this action, and the resultant repeated usage of the "hood", the young girl was always known as LRRH in substitution for the name identified on her birth certificate and other identifying documentation.

During one 24-hour interval, a request was issued by the MP for LRRH to deliver a package to the MP's Maternal Parent (MPMP) (genealogically identified as the Grandmaternal Unit (GU) with respects to LRRH). This package was to include:

  • cheesecakes
  • fresh butter
  • one dozen (12) strawberries

Little Red Riding Hood (LRRH) optioned to accept the Task Order (TO). LRRH further sourced a package delivery vehicle with the proper functionality for the Task Order, selecting a wicker basket. After a thorough and complete market survey, leveraging LRRH's experience with similar Task Orders in the past, cheesecake and fresh butter were acquired from the kitchen, whereas strawberries were acquired from the garden. While the latter item was not, strictly speaking, within the bounds of the Task Order, the marginal cost savings as compared to waiting for strawberries to grow in the kitchen appeared to be of great benefit to the MP in the completion of the Task.

With initial outsourcing complete, the journey was commenced by LRRH (see Appendix A: Proposed Map of Route Between the Domiciles of MP and GU). During a brief eleventh-hour meeting, MP issued a contract rider requiring the complete confidentiality of all personnel working the Task Order. LRRH assured MP that there would be no violation of this rider.

In the course of executing the Task Order, LRRH was approached by market competitor Old Grey Wolf (OGW). There were inquiries from OGW to LRRH regarding the nature of the Task Order, and in violation of the contract rider, LRRH disclosed sensitive and mission-critical data relating to the Task. Table 1-1 illustrates the nature of the information believed to have been compromised:

Table 1-1: Information Compromised by LRRH During Interactions With OGW

Nature of DataDisclosed ToSeverity of Disclosure
Contents of BasketOld Grey WolfMedium
Nature of TaskOld Grey WolfHigh
Destination of JourneyOld Grey WolfHigh

The identity of LRRH had been predetermined by OGW using standard practices of observation; therefore, that information was not compromised by the actions of LRRH.

It was the intent of OGW to compromise the functionality of LRRH, but the potential negative impact on its operations by the nearby presence of an organized unit of fully-functional Wood Cutters (WC) provided for the redirection of its action item to the domicile of GU.

Though LRRH had blatantly violated the terms of the contract rider, this violation went unreported to supervisory entities (i.e., MP) by the violator. LRRH continued to action the Task Order despite clear and compelling evidence that the integrity of the process had been disenfranchised by the OGW.

While LRRH continued to analyze its processes through the implementation of the Task Order, OGW leveraged its greater cumulative experience and used Best Practices to arrive at the GU client site in a more efficient and expedient manner than LRRH. Therein, the functionality of GU was impacted by the biorhythmic needs of OGW in a negative manner.

Upon the dissemination of information related to the pending closure of the Task Order assigned to LRRH, OGW engaged in an enterprise-wide analysis of situational readiness. Determining that there were vulnerabilities in OGW's methodology, OGW elected to redesign the external identifiers of OGW to better emulate those of GU, by means of garbing the nightgown generally associated with GU and altering the vocal patterns of OGW to align with precedents set by GU.

After completing the Task Order by delivering the deliverables:

  • cheesecakes;
  • fresh butter; and
  • one dozen (12) strawberries,

LRRH recorded observations of the host system. These observations included, but were not limited to:

  • My what big ears you have!
  • My what big eyes you have!
  • My what a big nose you have!
  • My what big teeth you have!

Upon receipt of the host system status analysis, OGW prepared and delivered a response regarding the functionality of the concerned functionalities, to include:

  • This functionality leverages the soundwaves generated from other sources, such as LRRH, to amplify the positive audio signal from such sources for the end user.
  • This functionality absorbs underutilized light emissions and their reflection from objects thereon, such as LRRH, to better provide for the identification of nearby entities by the end user.
  • This functionality analyzes the available transient atmospheric particles against a matrix of known particle cultures, such as LRRH, to provide near-instantaneous and transparent supplemental feedback to the end user.
  • This functionality greatly impacts the capacity of the OGW to reprocess physical assets related to LRRH in such a manner as to benefit the continued functional life-cycle of the OGW operations!!

Immediately thereafter, Old Grey Wolf (OGW) executed its asset plan action item and severely compromised the functionality of Little Red Riding Hood (LRRH).