Equipping Writers for Success
HOME   |   ABOUT US   |   CONTACT US   |   SITE MAP   |   MASTER ARTICLE INDEX   |   ADVERTISE WITH US!
HELPFUL LINKS   |   EDITOR'S CORNER (Ramblings on the Writing Life)

Getting Around...

Career Essentials
Getting Started
Queries & Manuscripts
Market Research

Classes & Conferences
Critiquing

Crafting Your Work
Grammar Guides

Research/Interviewing
Writing Contests

The Writing Business
Income & Expenses
Selling Reprints
Collaboration
Pseudonyms

Negotiating Contracts Setting Fees/Getting Paid
Rights & Copyright
Tech Tools

The Writing Life
The Writing Life
Rejection/Writer's Block
Health & Safety

Time Management
Column: Ramblings on the Writing Life

Fiction Writing - General
General Techniques
Characters & Viewpoint
Dialogue
Setting & Description
Column: Crafting Fabulous Fiction

Fiction Writing - Genres
Children's Writing
Mystery Writing
Romance Writing
SF, Fantasy & Horror
Flash Fiction & More

Nonfiction Writing
General Freelancing
Columns & Syndication
Newspapers/Journalism

Topical Markets
Travel Writing
Photography

Creative Nonfiction
Memoirs/Biography

International Freelancing
Business/Tech Writing

Other Topics
Poetry & Greeting Cards Screenwriting

Book Publishing
Traditional Publishing
Self-Publishing
Electronic Publishing
POD & Subsidy Publishing

Promotion/Social Media
General Promotion Tips
Book Reviews
Press Releases

Blogging/Social Media
Author Websites

Media/Public Speaking
Booksignings

Articles in Translation

Search Writing-World.com:

Google:
Yahoo: MSN:

This free script provided by
JavaScript Kit


Technical Writers: It's OK to Lie to Your Readers -- A Little!
by Geoff Hart

Return to Business & Technical Writing · Print/Mobile-Friendly Version

Although technical communicators must always provide our readers with correct information, that doesn't mean that the information must be completely accurate. Sound like a contradiction? Consider the following example:

My son once asked me why the sky was blue, and being a dutiful father, I told him. I started by casually mentioning light absorption and scattering, but that didn't satisfy him: he wanted to know why certain colors of light were absorbed, reflected, or scattered. So I explained how white light was made up of many different wavelengths, and that each wavelength was absorbed or reflected differently because of the physical properties of the molecules that make up our atmosphere. That didn't satisfy him either, so I dug a bit deeper. Each new answer generated yet another "why", and long before I invoked quantum mechanics and the interaction of light waves with electron orbitals, two things became clear: first, he was only asking out of stubbornness, since he'd long since ceased understanding anything I was saying, and second, I'd reached and surpassed the limits of my own knowledge. Eventually, I simply replied "because that's the way the universe is", an answer that relieved both of us.

True lies

Fortunately for those of us who write and edit technical manuscripts, this level of curiosity and stubbornness is highly atypical; if it weren't, we'd never be able to complete a documentation project because we'd never finish discussing the quantum mechanics of the File menu. As my anecdote reveals, sometimes going beyond the first and simplest explanation provides too much detail only confuses our audience. This means that technical communication is one of the few types of writing where it's acceptable to lie to your readers--at least in the sense that providing only as much information as they need to know, rather than the whole truth, is lying.

Unfortunately, this raises the difficult question of determining just how much detail we must provide to fully satisfy our audience's need for information. Answering that question depends on understanding just how much technical accuracy is truly necessary. At some point, "because that's the way the universe is" becomes technically inaccurate, but satisfies the reader's need for information. Going beyond that point to provide a fuller explanation may be more than the reader really needs to know and may actually impede understanding.

So how do you pick the correct level of detail? Consider the product you're documenting from the viewpoint of your readers. To them, accuracy means three things:

1. Visual fidelity Visual fidelity means that what you describe in your documentation matches what viewers see in the product closely enough that they won't notice any distracting differences. If you say that a feature is present, it must be present--but it must also be present at the location you described, and must look the way you promised it would look. Moreover, the word labels that appear on it must be identical to the word labels you use in the text. But if the surface texture is brushed, anodized aluminum, and you use a simple metallic color in your diagram of the product, that's acceptable; the differences between the two textures are unlikely to distract anyone.

2. Correctness Correctness means that readers should never encounter an experience that differs from the experience you described in your documentation. If a process takes five steps to complete, with specific details in each step, your description must contain exactly those details, and no others. If you explain that something works in one specific way, it must work that way, without exception. Where the possibility of deviation from your description exists, you must explain the circumstances that could cause the deviation, and whether readers should do anything about this deviation.

3. Completeness Once you understand intimately how readers will use a product, you understand all the details you must explain to support that use. The thing that separates good technical writers from product designers is that we have the ability to use a product the same way its intended audience will use it; the designers are usually too close to their design to achieve this level of empathy, and already know all the things the product's users must be told. Providing an incomplete description means that readers must fill in the gaps themselves. Providing a fuller description than what they need to accomplish their tasks generally won't help them do their work; in fact, it may slow them down because they must first read the unnecessary information before they can decide whether it's truly necessary.

Lie to them--but just a little

Understanding these three factors lets you determine just how much technical detail readers require. For example, readers don't need to know that saving a file on their computer's hard disk really means translating the file into a series of magnetic domains imposed onto a thin film that can reliably store those magnetic domains for a limited number of years. That's certainly interesting to geeks like me, but entirely irrelevant to the reader who simply wants to understand their word processor's "Save File" command. In contrast, users of the original Macintosh computers needed to understand that the trashcan icon on their computer was actually an incinerator that eliminated trashed files as soon as they shut down the computer. (But as in my first example, they didn't need to know about the magnetic heads that erased the information from the disk.) In both cases, the level of accuracy required is the level that affects how the readers use the software--and nothing more. So in a very real sense, it's okay to lie to your readers by presenting them with only the information they need to know, even if there's more to be known. How to determine what they need to know is a matter for a future article.

Find Out More...

13 Tips on How to Tech-talk to Non-techies - Hasmita Chander
http://www.writing-world.com/tech/techtalk.shtml

KISS - Keep It Simple, Sweetheart: How to Write About a Complex Subject in a Simple Way - Devyani Borade
http://www.writing-world.com/tech/KISS.shtml

Succeeding as a Technical Writer - Michael Knowles
http://www.writing-world.com/tech/tech1.shtml

Copyright © 2001 Geoff Hart
This article may not be reprinted without the author's written permission.


Geoff Hart is an associate fellow of the Society for Technical Communication (STC), and works as a writer, editor, translator, and information designer specializing in the sciences. With nearly 20 years of experience in scientific communication, he is a frequent contributor to the techwr-l (technical writing) and copyediting-l (editing) Internet discussion groups and to several STC newsletters. Visit Geoff online at http://www.geoff-hart.com/.

 

Copyright © 2017 by Moira Allen. All rights reserved.
All materials on this site are the property of their authors and may not be reprinted
without the author's written permission, unless otherwise indicated.
For more information please contact Moira Allen, Editor

Organize your writing
and save time. Click here for a free download