Do I REALLY have to understand the material?

Subject: Do I REALLY have to understand the material?
From: Andrew Plato <gilliankitty -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 20 Aug 2002 02:48:01 -0700 (PDT)

Got the typical litany of responses, to my "Do I have to understand the material"
thread. I've honed them down to these 7 counter-arguments.

>>> 1. It seems like any work you deem as unimportant is called "fun work?"

"Fun work" or "one-off" tasks are anything that is not a bottom barrel necessity
to get a documentation project done. This often includes such tasks as:
developing style guides, building templates, setting up a single-sourcing system,
choosing fonts, worrying about ?information mapping,? or any of the other
?process related? stuff that distracts a writer from planting their ass in a
chair and writing the damn documents.

The problem is not that any of these things are worthless. Its that they tend to
divert people's attention for too long. Writers spend all their time worrying
about their single-source system and then they don't have time left use their
amazing new system to actually produce any documents. As with all things, there
has to be balance. I?ve posted this chart before.. If you look at a project as a
whole, time should be divided up as such:

5% Setting up templates, style guides, single-sourcing, fonts, etc.
35% Learning the technologies, products, and services.
25% Physically sitting at a computer and typing in text.
30%% Editing, tweaking, refining
5% Publishing, printing, PDFing, etc.

Now, my previous times and percentages may be different, but the core concept is

In short, the overwhelming majority of a writer's time should be devoted to
learning and understanding the technologies and products he/she is documenting.
The remaining overwhelming majority of the time should be spend writing and
editing. A tiny fraction of time should be devoted to organization and

The problem is that most people don't like writing and editing. That is *hard*
work. Setting up processes and theorizing about how to make your work more
efficient is considerably more entertaining and emotionally satisfying. So, lame
writers will find any excuse they can to redirect their jobs into "fun work" and
sock off the *hard work* on the programmers.

This is the fundamental problem with most single-source solutions. The writers
become obsessed with designing a better mousetrap, such that they never have time
to use it to catch mice. Which basically makes their entire mousetrap building
effort pointless.

>>> 2. The user doesn't care about all these technical terms, they just want to
do their jobs. So why learn this technical stuff? I should be learning the user's

Yes, but learning the user's job is half of your responsibility as a writer. The
other half of your job is to understand the technologies and products those users
must use. This ensures that you are giving accurate and relevant information to
the user and not merely capturing procedures.

A writer must bridge a gap between some complex technology or product and a
user/reader who wants or needs information. Hence, your job is to consume all the
information you can, and then feed the relevant pieces back to the reader.

A writer can't do that with any degree of accuracy or skill if they do not
understand the technology. Writers can't just pick an chose the information they
find most pleasing. They have to consume ALL the information, whether they like
it or not, and then make intelligent and insightful decisions about what
information is most relevant to the reader.

If you only have 1/2 the information, then you are making decisions based on 1/2
the data. And therefore, your documents will be about half useful and half
useless. Actually, they'll probably be more like 1/3 useful and 2/3rds useless,
because after you filter down that 1/2, you won't have a lot of insight left.

Incidentally, a person who consistently operates at 33%-50% capability is not a
terribly desirable employee.

>>> 3. It is not my job to make products and technologies more desirable, that is
marketing and sales job.

This is perhaps the largest and single-most destructive idea out there. It is
perpetrated by a mindset of isolation. These are the same people who would fold
their arms and defiantly refuse to work because some task was "not in my job

In the minds of executives, documentation is only useful when it adds value to a
product/service/technology. Otherwise, it?s a waste of money. Why spend money to
document a product if it adds virtually no value to the product? Companies
document their goods and services to make them more appealing to users. A product
with good documentation can (and should) help a product sell better. I have first
hand account of this fact.

Hence, a good writer will always integrate sales and marketing issues into the
material. Not only does this ensure consistency of message, it also reassures
readers that the product does what it says.

Isolation is NEVER a productive business tactic. When writers isolate themselves
from other departments, the quality of docs always, without fail, plummets. This
is simply because the writers lose touch with the bigger picture.

>>> 4. Programmers, for the most part, don't understand how the user will use the

Programmers generally have a pretty good idea how users *****CAN***** use the
program. The writer?s job is to work with them to understand those capabilities
and then integrate them with the user's needs.

Programmers are not totally cut off from users, incapable of understanding their
needs. Likewise, the technical writer is not some "lone savior of the tender
user." Programmers tend to have rather well developed ideas about how a user can
use the product. The writer's job is to learn those ways, then integrate that
with the user's needs. The only way this can be done with any level of
proficiency is to learn the technology.

>>> 5. Technical writers are advocates for the user!

This idiotic idea has percolated through tech comm for years, mostly by font
fondling twits that want to avoid the job they were hired to do.

Technical writers are translators of technical information. The ultimate job of a
technical writer is to understand the user?s needs, learn the technologies, and
then deliver the appropriate information to the user. If anything they are
advocates for their employer's goods and services.

Users are not fragile little kittens that must be protected by greedy filth
covered programmers. They just need information delivered to them in a coherent
and logical manner. They don't need frickin' advocates.

If you want to be a "user advocate" then get a job as a UI designer, a producer,
or some other role where you are developing products for customers. Writers
produce documents that describe goods and services that other people designed.
And many programmers, producers, etc. are not going to take well to you assuming
a job you were not hired to do.

This is not to say there isn't room for some help with user interface or work
flow. GOOD writers who consistently prove their ability to accurately and
insightfully document a product often get asked to assist with development
issues. But rarely is the entire role of user design handed over to a writer just
because he/she perceives himself as an "advocate for the user."

Incidentally, most UI designers are programmers.

Writers bridge a gap. Between techie and newbie. That means playing both hands
well. Being able to talk newbie AND techie. If all you do is focus on talking
newbie and never talking techie, then you?ve missed half the job.

>>> 6. If I document, for example, manufacturing programs, its more important for
me to understand the manufacturing process than the language that the programs

Yes. But learning the programming languages surely won't hurt your ability to
understand and document manufacturing processes.

There seems to be this notion out there of "limited knowledge." I hear people
saying all the time things like "I can't possibly know all this..." or "this is
won't help me, so I won't learn it." Your brain is not a hard drive that can
only fit 100 GB of data. When you get to 99.9 GB, you have to start deleting
knowledge so you can fit new stuff in. Your brain can learn and understand a
virtually unlimited amount of information.

Hence, learning C++ will not suddenly make you incapable of writing
documentation. Presumably, if you were a good technical communicator before you
learn C++, you'll be an even better one after you learn C++...because now you are
not only a good writer, you're a good writer who understands C++. That makes you
more valuable to employers and will help you understand the technologies you're
documenting. Mostly, you'll gain a little more respect for what the engineers and
programmers are doing, and as such you'll be able to describe features and
capabilities with a little better insight and authority.

Moreover, learning technologies will also expand your employment options. The
more you know, the more valuable you are in the career market. If writing
declines, and you know C++, you may get a job as a C++ programmer?which will
likely pay more as well.

>>>7. This isn't why I got into writing. I don't want to learn this technical
stuff. I just want to write.

Maybe you should consider a different profession. You can't be an airline pilot
without learning how to fly a plane. You can't be a (good) technical writer if
you won't learn technical stuff.

That's my first round of counter-arguments. I am sure there will be more.

Andrew Plato

Do You Yahoo!?
HotJobs - Search Thousands of New Jobs

Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at

TECHWR-L is supported by ads and sponsorships...and donations.
You can help maintain the TECHWR-L community with donations

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.


Previous by Author: Do I have to understand the material?
Next by Author: Re: MOSTLY OFF-TOPIC: Communicating with the Academic Community
Previous by Thread: OT: Well, not really...
Next by Thread: Re: Do I REALLY have to understand the material?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads