A publication that features ideas for writing step-by-step procedures and troubleshooting support documentation for electronic, Internet, and print distribution--and much more!

 

Do the words make sense?

The generally accepted words and phrases of technical idioms may add sparkle and familiarity in technical documents, but they assume that all readers will understand what is being communicated. For people without the assumed common education and experience, as well as those who don't speak English well, idioms can be difficult to understand. If the document has to be translated into another language, accuracy may be hard to achieve unless the translator is thoroughly familiar with the idioms and the subject. The computer industry provides a good example of the problems of using such expressions to describe new and unique concepts and activities.

Examples:

• Inappropriate phrases:
  Select the option.
  Mouse down the menu and select the option.
• Appropriate:
  Use the mouse to point to an onscreen image artifact (like a button) that references an option; then, tap a button on the mouse to select or deselect, enable or disable the option.

The accuracy of the phrasing in this Appropriate example requires much more space. Readers who have been schooled on brevity must be highly motivated to read more than a few statements of such length. Composing accurate descriptions can be difficult and the results could be just as confusing for some readers as brief descriptions using idioms. You must know your audience. Are you educating them, telling them why; or instructing them, telling them how; or a little of both. In documents where the same description is repeated more than twice, use the shorter phrasing and support its idioms with a reference box containing appropriate definitions and procedural descriptions.

• Inappropriate phrase:
  Select the text.
• Appropriate 1:
  Use the mouse's text insertion bar to "highlight" the text to be moved.
• Appropriate 2:
  Point to the start of the text; then press the mouse's left (or only) button while moving the bar over the text. The selected text or its immediate background color will change.

The Inappropriate phrase is only inappropriate for a first use in a technical document. It would be appropriate if used in the document after Appropriate 1 and/or Appropriate 2 where it is assumed that a reader previously read the others or if the complete description was in a reference box of keyboard and mouse techniques.

• Inappropriate phrases:
  Issue (or enter) the following command: AUTOEXEC.BAT
  Key in this command: AUTOEXEC.BAT.
• Appropriate:
  At the onscreen prompt, type: AUTOEXEC.BAT

You don't key a character, you type it. Typing imply the use of a keyboard. The original IBM keyboard design did not include a "dot" character, because it was based on the pre-PC Selectric typewriter. Contextual and hyphenation dictionaries cannot distinguish a period used as a dot within a computer command statement or address. If you can't subscript a bullet for this purpose, make the period/dot bold: AUTOEXEC.BAT. The bold typestyle should differentiate the dot from a period.

• Appropriate:
  At the prompt, type: D FFFF:5 L 8

For onscreen commandline text, use a font like "Courier" with identical spacing for all characters so that the spaces between command elements, if any, can be easily seen. To avoid confusion, omit the end-of-sentence period; unless it is a character included to be typed. For readability, change the color of the text; bold is acceptable. If there is sufficient space, separate the code from its paragraph; use a new line or lines&emdash;make sure no hyphens are inserted by your spellchecker.

 
• Appropriate:
  Tap: [F3] key while pressing: [Command] key.

People do not click on a keyboard key, they either quickly, briefly "tap" it, or "press" it for a longer period of time.

Some projects allow the author to develop creative style elements; the words used and their placement on the page. Even simple style elements can be effective; such as, italicizing active verbs in declarative sentences where the implied subject is the word "you."

There are several style considerations for representing computer keys.

More Examples of inappropriate wording:

• · No one "turns on" a computer's power, they "poweron." The computer has a power switch or button or a keyboard key that is pressed and/or a three-position (ON/OFF/ LOCK) key that is turned to the: ON position. Computers are not old-style TVs or radios with a POWER/VOLUME knob that must be rotated by hand to an: ON position.
• · Don't state: "turn on" or "turn off" an onscreen option; again, nothing is physically turned. Enable or disable the option by clicking on its onscreen selector box or button.
• You don't jump or jumper a jumper block, you insert a jumper wire into the jumper switchblock.
• · Hardware is manufactured. Software is published on paper, on disk, or electronically.
• · For more examples, review Using Jargon.
• · Consider: The words don't make sense; but its too late to change common usage.

"Words making sense" and other concepts are thoroughly explored in the book: Technical Writing with Style.

The words don't make sense; but its too late to change common usage

Examples:

• · Is it a floppy drive, a hard drive, a CD drive? What is a drive? How does it differ from taking a drive? Learning to drive? A Sunday drive? Or a car parked on the drive. This is a good example of a badly chosen word, made common by marketing and advertising professionals.
• · Do you really "run," "open," or "enter" a program, file or drive? Or just activate it.
• · Do you really "stop," "close," or "exit" a program, file or drive? Or just deactivate it.
• · Do you "make" or a file? Or just use an application to "define" it (with code).
• · Do you "recycle" or "trash" a file? Or just "unallocate" the data storage space it once occupied.
• · Is it an onscreen image or an image on the screen? A tangible thing is on the (CRT's glass) screen; text or graphic art is onscreen.
• · Do you "bring up" a file or window? (If so, from where?) Or just make it appear onscreen. ("Appear a file" makes more sense than "bring up a file;" although this would be a new use of the word.)
• · Is it really a case in point (or better, caseinpoint), or just an "example."
• · Are interconnections better than connections?
• · Are interlinks better than links?
• · Did you sleep with the embedded hardware and software?
• · When you "lookup or look-up" a word, do you hold the dictionary over your head? (Lookup, like lockup and hookup is a single word. Update your spellchecker.) For brevity and accuracy use: find. I "find" words. I "found" words.
• · If someone is taller than you, should they "listen up" to you or just listen to you?
• · When housecleaning a computer's application and data files, open the windows to let in fresh air.
• · Obviously you don't "plug in" (or "plug out") a cable. If you plug a leak, you insert a plug into a hole to stop the leak. You may plug a rock into a hole, or even insert a plug into a hole; but, an computer's interface is not a hole, it has sockets or pins. It does the opposite. It opens an access for data to flow through the cable and interface. It is more accurate to state: "insert the cable's connector," than "plug in the cable." Don't state: plug the plug in.
• "Plugin," a noun, is a relatively new word as badly conceived and used as any before it. It is a software utility that enhances the functionality of an application. For a image-editing application, a plugin might provide special effects to alter an image's appearance. For a Web browser, it might provide audio or video support for hearing recorded speeches or viewing a movie retrieved from a Web location.
• · How different the real-world is from what is real in the world?
• · Were you in a vehicle when you were driven to do it?
• · Is it an operating system or code that operates a system of associated devices and software applications?
• · What is the price for paying attention? (The assumption is that the one who is receiving the attention has paid for it; i.e., I am paying for your attention.)
• · Do you "setup" a computer or just set it up on top of (or place it on top of) a table or desk? Is the opposite of "setup," "set down?" No it is "disassemble" or "take apart" (or better, takeapart). Therefore, "assemble" is a more accurate word than setup.
• · Do you "tuneup" or "tune up" a device? (If so, how high up is it tuned?) Or just "tune" it.
• · When troubleshooting, what happens if they shoot back?
• · Is it user-configurable or just configurable if any user can do it.
• · It may be useless, but someone must ask what do users use? Is it useless, or just used less for some reason.
• · Was it useful, or full before it was used? When there is a fire, a full bucket is of more use than one less full.
• · When operating ontime and in real-time can you be offtime, overtime, and out-of-time? Obviously, there is no time to consider the now; instantly it would be the past.
• · What is better than user-friendly? While you can't recover from some friendships, you would hope to be forgiven. To be able to undo backward, then forward again, as many steps as desired; perhaps recording some steps for future use and consideration that is forgiveness!

Comment:

How "common" is "common sense?" Usually, it is a choice between what sounds better versus what is sufficiently descriptive. You should be concerned that people who follow your instructions, do so as quickly, efficiently and safely as possible.

For instructions, don't just write: "insert the board." Rather, describe the procedure: "Hold the (adapter-, expansion-, logic-, system- mother-, daughter-, or circuit-) board by its edges, align it with the socket; then, press down while gently rocking it end to end until it is firmly in place."

This statement may be too brief: "connect the cable." (To what?) It may be better to use: "Insert, fit, (or plug?) the cable's connector into the serial interface on the back of the computer case."

"Common usage" and other concepts are thoroughly explored in the book: Technical Writing with Style.

Analogies, euphemisms and idioms of languages, professions and industries

The assumption for including such words and phrases is that both the author and audience understand them. Booting-up a car, undoing a meal, downloading a plane, revving-up emotions, plugging-in a door, eating a file, flying a subject, and similar expressions are baby babble. Such incongruous expressions may be constructed out of circumstantial frustration more often than misunderstanding. At first repeated with humorous intentions, the punchlines are too soon forgotten. I'm not dising you, it be true.

Yes, people react to the misuse of words and phrases. Most will still understand the speaker's or writer's intention; but how many will continue listening or reading without interrupting the process to reflect on the inappropriateness. After such reflection, only the seriousness of the content will determine if they continue listening or reading. The

speaker or writer, as well as the content, are diminished in the listener's or reader's impression. Even commonly used phrases can make an impression opposite the one intended.

Examples:

• · Claiming success by stating: "the whole nine yards!" instead, indicates a failure to achieve a goal. In football, ten yards are required for a first down.
• · A comment (or point) is "well taken." But, where did the speaker take it? "Take" and "taken" are not a substitutes for the words "understand" and "understood." Perhaps this term derived from an analogy of a debate to a sword duel. "The point of your sword passed my guard, but did not enter my flesh." OUCH! (Smile when you say that. )
• · A comment (or point) is "well made," only if it is presented in a clear and precise manner and contains no ambiguity. ( Your sword has no defects.)
• · A comment (or point) is "well received," if no one took offense with its content. (Thank you.. )
• · Laying the ground work for , requires moving or removing dirt and adequately supporting everything on top of it.
• · Case-in-point, Whatever the statement, whatever the case, it will never be just-in-case-in-a-point; although some may make-the-point or quietly point-out, that the end of a point's tip is infinitely small. Unfortunately, the pen's point was damaged inside that case.
• · Making a level playing field while the game is afoot, requires moving and/or removing dirt. Under such conditions, tactics and strategies must include finding those who have been buried while looking for the ball.
• · When an analogy is based on anal logic, what you assume may make an ass out of u and me. (A typical two-moon conjunction!)

These concepts are thoroughly explored in the book: Technical Writing with Style.

Abusing commonly used phrases

Commonly used phrases can make an impression opposite the one intended even when properly used if there are too many of them. One may be nice for spice, but two or more is an excess to be avoided in any technical document.

Examples:

Whatever you have on hand, on the one hand or the other, first hand or second hand, you may not be able to lift by hand (no matter how many you have) If you have it well in hand you may feel satisfied "look Ma no hands!" Asking for a helping hand is a handy phrase, most people expect money in it before giving a hand. If your hand is forced and you show your hand, don't throw your hand in too soon, no one wants to

be empty handed. Remember, don't lay hands on them. Don't use a high hand. Don't throw up your hands or a heavy hand may take you in hand. We all want to be even handed, to wash one's hands of despair, to have clean hands, to keep one's hand in the game. With so much of the human brain devoted to the managing thumbs, why doesn't the left hand know what the right hand is doing. Hands down, hands up, hands off, its so confusing.

With a handshake, the handsome handyman agreed to help the handmaiden fix the handlebar on her handcart. But it was just a handicraft, a handiwork ill equipped for a race. No handicapper would predict a win with its handicap missing handgrips. She suggested using her handkerchief, it was hand-knit by her mom with handpicked yarn. She pulled it out of her hand-me-down, handmade handbasket. Hand in hand they readied the handicraft. You have to hand it to them for their sense of adventure. Hand-over-hand, they pulled it up the hill by rope. She sat in the handcart. He cut the rope with a handaxe and down the hill it seemed to fly. And in her hand an empty handbag which she hoped to fill with a prize.

Using foreign language words

Try to avoid including foreign language words in your document unless one or more of these are true:

a. They are commonly accepted among people who speak English.

b. Describe a thing, event or process that is commonly understood to be identified with the country or region where that language is used.

c. The word or phrase has greater accuracy and succinctness than any substitute in English.

d. There is no appropriate English language substitute.

e. The foreign language word or phrase is used to support an image appropriate to the document's content.

Never use foreign words if you don't know their full meaning; not just the brief definition as may be found in a "language-to-English" dictionary.

Readers shouldn't have to translate to understand what you wrote. If you must use foreign words and phrases, distinguish them from the rest of the English language document with bold or italic characters and/or by placing them within quotes. As a courtesy, consider placing the translation in brackets on the same page or opposite page (if footnoted).

For languages that use the same alphabet as English, you have a choice between using the same spelling with accents as used in that language, the foreign word without accent, or a transcription of their sounds as may be interpreted by a person who only speaks the English language.

If you have to use foreign words with accents, make sure you spell them correctly, so that they will have the intended meaning. There are foreign-language typefaces that include the necessary accents. Use one of these fonts, if you include a paragraph or more of such text. (There are many accented characters supported by Windows and MacOS.)

If the foreign words that have been accepted into the English language; such as, cliche, don't include accents.

Transcribed words should not be accented; but, dashes may be inserted for pronunciation. For languages that use other alphabets (like Russian and Arabic), or are character-based (like Chinese and Japanese), there will probably be transcribed English versions of the names of towns, cities, geographical features and people. Help is probably available from that country's embassy.

If there is no transcribed English version or foreign words and phrases, represent the pronunciation in English as best you can. When you do, be consistent with the sounds of letters and combinations of letters. Again, notify the reader of your transcription efforts. If a lot of different foreign words have been used, consider including a Glossary of Terms.

For languages like Russian, don't use characters in the English alphabet to represent similar-looking characters in the other alphabet. For example, the Russian pronunciation for: B is ve (as in vat ), E is ye (as in yet ), H is n (as in net ), P is err (as the r in better ).

These concepts are thoroughly explored in the book: Technical Writing with Style.

Using jargon

When you use words and phrases that are associated with an industry, profession or cultural group, define them in the same sentence. The English language is constantly evolving; new words are conceived or accepted from other cultures less often than generally understood words are given additional industry-specific definitions.

The degree to which you are familiar with an industry is equal to your use of its jargon; but this leads to self deception when writing for people with little or no experience. Your vocabulary becomes "polluted" with idiomatic expressions and suppositions.

The computer industry has its own language, for example. Even highly trained technicians who speak only English have problems fully understanding the terms and concepts. The word "memory" can be used to describe the capacity of a data-storage drive, data-handling capacity of RAM (Random Access Memory) chips, and utilities that mimics or manages the functions of drive or chip. The confusion is increased by the introduction of thousands of new products, and new versions of products (with new features) each year. (Some of this is covered in: Do the words make sense? )

The solution is to be selective about the technical words you use, and in the same sentence, to include the extra words that define them. That's the difference between good and better instructions.

Examples:

• Use: memory allocation of RAM chip capacity
  Not: set the memory (What?)
  
• Use: partition the data storage drive's capacity .
  Not: partition the drive (What?)
  
• Use: on (Finder's/Window's) onscreen desktop
  Not: on the desktop (What?)
  
• Use: insert the cable into the serial cable interface
  Not: plug in the cable (Where?)
  
• Use: the mouse's pointer to select the menu item
  Not: select the item (How?)

Comment:

Consider a four-year-old child who has never seen a microwave oven. Do you just tell them to: "Nuke the cheese sandwich." Or do you go into a little more detail. The type of dish to use and what not to use. (No metal forks, spoons, pie plates, etc.) How to open and close the door. How to set the temperature and cooking time. And so on.

These concepts are thoroughly explored in the book: Technical Writing with Style.

Now Shipping an expanded
Technical Writing with Style
- SECOND EDITION -
For 2000

Book Pricing

Visit our

Return to top