TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Are your documents interesting? From:"Nuckols, Kenneth M" <Kenneth -dot- Nuckols -at- mybrighthouse -dot- com> To:"Dick Margulis" <margulisd -at- comcast -dot- net> Date:Thu, 12 Jan 2006 12:50:54 -0500
Dick Margulis said...
>
> Steven Brown wrote:
>
> >
> > Of course the answer is yes! The challege to us tech
> > writers is convincing management that users are,
> > well...just like us! They laugh and cry. They watch
> > the same TV shows, read the same magazines. They speak
> > informally. Why does the tone of our documents and
> > training not reflect what people are used to
> > experiencing in the larger marketplace?
> >
>
> All together now: IT DEPENDS.
>
> We've had numerous go-rounds on the list about when, where, and if
> humor, for example, has a place in tech writing. And we just had a
> thread about contractions. The same considerations apply to
> conversational writing style in general.
>
> In the instructions for swapping out a coolant pump on a nuclear
> reactor, you probably don't want to be too loosey-goosey with the
> language. Or in the instructions for filling out the forms for
Medicare
> Part D, either. The user guide for the latest video game is another
story.
>
> The two big considerations, from management's point of view, are:
>
> 1. Is there a chance that someone with limited reading skills is going
> to misunderstand the document and end up causing harm to budget,
> equipment, or persons?
>
> 2. Is it going to cost extra to hire writers capable of writing an
> interesting document?
>
> If you can answer No to both questions, go for it.
>
The consideration I use is the fact that my users / readers generally
have a time constraint and are generally operating under a stressful
environment (tech support, installation, restoration, etc.). I might
want to do something to relieve some of that tension by being humorous,
but humor is a tricky thing and it can be extremely hard to do when
written for someone in a professional environment. Someone who is not a
native reader of English may not understand wordplay or subtle shifts of
meaning a writer might use to elicit humor. Written humor also can't
rely on physical or audio cues to humor, and it can take the reader
longer to process that what I'm telling him or her is a joke. With the
documentation I create, anything I do to waste my reader's time makes
him or her annoyed with me, and I don't find that very funny.
Therefore I avoid (intentional) humor in my documentation. Dick does
make a good point. If you're documenting a video game or writing a
manual for _enthusiasts_ to make repairs to a car or something (the VW
Repair manual that was cited on the list in the past couple of days
comes to mind), then humor might be entirely appropriate to put the user
at ease and keep them interested.
But when someone has to use your documentation to complete a task that
has a lot of stress, IMO the best thing you can do is present the
information with clarity, precision, and only as much additional
explanation as the user needs to complete the task. Don't waste their
time or try to be funny. That's just my personal preference.
CONFIDENTIALITY NOTICE: This e-mail may contain information that is privileged, confidential or otherwise protected from disclosure. If you are not the intended recipient of this e-mail, please notify the sender immediately by return e-mail, purge it and do not disseminate or copy it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
