Re: What are we? (also, Killer Language, Marketing vs. Developer)

Subject: Re: What are we? (also, Killer Language, Marketing vs. Developer)
From: Deidra McGee <dmcgee -at- HP1 -dot- NENA -dot- ORG>
Date: Wed, 20 Nov 1996 02:28:16 -0500

At 12:06 19/11/96 -0700, you wrote:

RE: I agree with you wholeheartedly Alisa. Audience is THE factor when
writing a technical piece. I could tell you needed to get this off your

Deidra L. McGee
Drexel University

>Communicators. Whatever it takes, whatever media, whatever terminology,
>whatever length. To quote an article from the STC Journal 2Q (I think):
>"We take the information from those who have it, and provide it to
>those that don't." I would add "in a form that they can use."
>The tools, software, grammar, punctuation, skills, methodologies,
>languages, lingo, etc., are all used to communicate. We must balance
>them to provide what the audience needs. I see so many people who
>get hung up on which software is better, what terminology is best (see
>"Killer Language" thread), and so on. I believe that it all comes
>down to what the audience is expecting and needs. "Usability" is now
>a trite word, but it is still a necessary concept.

>When I trained software, the first lesson I learned is that the vast
>majority of people really do *not* care about the bells and whistles,
>the fancy stuff, and what hoops the developing team had to jump to create
>the software. The end line was usually "How does this make my job
>easier? Will it keep my boss off my back? How can I use this?"
>That's it.

>I see myself as the last chance that the end user has to provide
>input into the product/documentation before being stuck with it. I
>try to put myself on the other side of the screen, and be the user
>(sounds Zen, yes?). I try to ask the questions that the user may ask,
>make the mistakes the user may make, and use the product in the way
>the user would. Best option, of course, is to have actual users test
>the documentation/product before release; however, in my 10 years in
>this career, I've never seen it done. I have attended classes in
>programming and various industries so that I can understand the users'
>needs. This also assists in communicating between developers and users
>because I can "sling the lingo" with both. It also gets the developers
>to trust me with their material, because they can see I write about
>what they are creating and understand the consequences of changing

>If the audience will be engineers in a specific industry who have been
>trained to expect specific terminology that is meaningful to them,
>use it - this includes "abort," "male/female," etc. If the audience
>is a bunch of knitters, use the terminology that is meaningful to them
>("knit," "perl"). If the audience is the general public, keep in mind
>the range of possible reactions to any terminology, and choose the
>most appropriate. This is actually true for all the audiences. I
>always reread to see if there is a chance for misunderstanding. If
>I see one, then I rephrase as necessary to eliminate it, if possible.

>Some of the first questions I ask when I create a new document are, "Who
>is the audience? How will they use this? What do they want?" It's
>actually very sad how often I hear, "I don't know." There are many
>times where the developers had never worked in the industry for which
>they were designing a product. This is also true for the marketing/sales

>How can they create a meaningful, useful, and profitable product
>for an unknown audience/industry? They seem to think that they can
>guess at it, and it will work. Many times, it's the concept that they
>are the only provider, so the user will take it because there is nothing
>better. I've heard so many times "Well, it's better than it was."
> The problem is that it still is not good. BTW, all of this applies
>to documentation, too.

>In the "marketing vs. developers" thread, I've noticed the barrier is
>usually when Marketing promises whatever the customer wants without
>researching whether it is possible, and Development figures that whatever
>they create is so nifty-neato that anyone will want to use it. I've
>had many instances where the developers wanted me to describe the algorithms,
>statistical theories, "theory of operation" that they invented for
>the product, just to show off how smart they were to do it. I've had
>Marketing tell me not to mention negative or potentially damaging aspects
>of a product because it wouldn't be good for the corporate image.

>Every now and then I introduce myself as a fantasy writer, since this
>is a push that I've received in the past. However, for my professional
>ethics, self-pride, and commitment to the audience, I insist on documenting
>reality. I try to make it as palatable as possible ("it's a feature,
>really!"), but it must be real.

>Speaking about the conflict regarding whether to include "marketing
>material" in technical documents, I believe there is no conflict.
>Of course, it must be balanced with the needs of the audience (who
>wants to read three pages of advertisement when they just want to find
>out how to turn it on?); however, I see no problem with introducing
>the company, the product, maybe other company products, usability/features
>of the product, and so on in a *brief* introduction. If the user chooses,
>this section can be bypassed to get to the meat of the document. The
>inherent snobbery that a technical document should only have technical
>content can and will interfere with the audience needs (you know, the
>reason why we're doing all of this). Also, the primary purpose of
>the product is to be sold; without this, the senior programmer mentioned
>in one message would be out of a job.

>IMHO, the software issue is in the same vein. I always welcome the
>chance to learn new software and technologies for multiple reasons:

>o I am more marketable.

>o I can produce my product in the most efficient way possible.

>o A prospective client or employer does not want to have to train me
>in the tools of the trade. I can become immediately productive.

>o I learn new methods for communication. Hopefully, these new methods
>will increase the probability that the audience will find my product

>o It's fun!

>Of course, there are fads and fashions in our industry that do not
>add much to what to we do, but even then, there is a chance that they
>may make a positive contribution. I always look at the appropriateness
>of any new technology I encounter, and then decide its usefulness.

>One advantage is that the new technologies encourage the audience to
>actually use what we create. It is a lot more fun to browse a
>graphical document online that it is to page through a printed manual.
>However, if the information is better suited for a specific media,
>use that media, if possible.

>The software and methodologies are tools that we use to create what
>we communicate. Just like a carpenter will perform better with a saw
>and hammer than with bare hands, we use these tools to create a better
>product. I do not consider myself a robot for learning and using these
>tools, just like a hammer and saw cannot build a house by themselves.
>I've yet to see a software that can research a product, create a content
>outline, create graphics, write content, format content, test usability,
>and publish, all from scratch. Until then, I'm secure that I can provide
>a useful service and product in my career.

>When I demonstrate that I provide added value to a product, my
>coworkers, developers and marketers alike, treat me like I am a
>professional and a member of the team. If the customers mentioned that
>my documentation was a valuable part of the product,
>then I did my job and earned the respect of my coworkers.

>We must also act like professionals. In the case of Sella Rush,
> ("Now I'm wondering how to remedy the situation, because I fear
> the attitude might spread. Is the only way to get professional respect to
> refuse to do some jobs? Did I go too far in my willingness to pitch in
> where ever needed? It seems like there's a fine line, which I've
> apparently dug a trench through! Basically, though, I'm just intensely
> irritated that my good intentions are being taken advantage of."),
>I believe she did go too far. There are many people who still see us as
>glorified word processors, and if we act like such, we will be treated as such.
>To balance this, her desire to pitch in and help was highly admirable, and
>I'm not knocking it in concept. However, if there were administrative
>available to do the data entry, the fact that Sella did it put her in the
>same clerical category for these developers. Now she will now have to break
>a behavior pattern with these developers that she set by allowing them to
>treat her like that. There are times when I've done data entry, copies,
>whatever was necessary. However, I draw the line at where it starts
>to become clerical and administrative duties, vs. my primary duty as
>a technical communicator. I wouldn't expect the developers to empty
>my trash, they shouldn't expect me to type their letters.

>My next point is that I do not agree the concept that our skills
>as communicators can be primary to being good writers.
> (Per Kevin Feeman's writing: "My point being, an individual
> can be a mediocre to poor technical writer/editor and yet be a
> great technical communicator. The reason I say this is that a
> person may have great document management skills, ability to
> identify customer needs and do an analysis, project tracking
> etc. in addition to document design, Web Pages, etc., yet have
> mediocre writing and editing skills.")
>If the user has to continually stumble over poor phrasing, sentence structure,
>and grammar, it will interfere with communication. It will also give
>the impression that we don't care about the quality of what we create.
> I would not want to buy a new car that had a poor paint job, even
>if the engine sounds good. My impression is that if the manufacturer
>didn't care enough to do the paint job right, where else were corners
>cut? We are judged not only by the content of what we create, but
>also its presentation.

>I see technical communication as the new generalist industry. The
>more we know, the more useful we can become. We cross industry, political,
>language, and cultural barriers. We touch everything, from road signs
>to training in heart transplants. WE ARE EVERYWHERE!! ;) In today's market,
>the new technologies seem to come quicker and quicker, and if we don't
>keep up, we won't be marketable.

>It may seem that our communication skills are a lower priority, but to me,
>it is all the same ball of wax. Just like the medical industry must
>stay current with new knowledge to provide the best care for the
>patient, so must we. I personally would prefer a modern doctor to one that
>was trained, say, during the Civil War. At the rate that new technologies
>are created, I would say the knowledge gap is just about the same every
>5 to 10 years for us as the Civil War to today is for doctors. But
>whatever the technology, the priority must always stay with what is
>best for the user (or in our analogy, patient).

>Our primary concern must remain the audience. Of course, we must temper
>this with the time, budget, resource, etc., issues, but if the stuff
>we create is unusable to the audience, all the rest of this wasted

>There, that's my diatribe for the day. Did it sound pompous enough?
>Class dismissed. ;)

>Alisa Dean
>Sr. Technical Writer
>alisa -dot- dean -at- mci -dot- com

Previous by Author: Re: Results of "Tool" survey
Next by Author: Microsoft Style Guide
Previous by Thread: What are we? (also, Killer Language, Marketing vs. Developer)
Next by Thread: Audience Analysis

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

Sponsored Ads

Sponsored Ads