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

[Alisa Dean <Alisa -dot- Dean -at- MCI -dot- COM>]

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
content.

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
people.

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
useful.

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 assistants
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
anyway.

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