Re: Important Stuff They Don't Teach In Tech Writing School

["Ned Bedinger" <doc -at- edwordsmith -dot- com>]

----- Original Message ----- 
From: "Andrew Plato" <gilliankitty -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Friday, August 27, 2004 9:16 AM
Subject: Re: Important Stuff They Don't Teach In Tech Writing School


>
>
> "Jerry Muelver" <jerry -at- hytext -dot- com> wrote in message
news:248045 -at- techwr-l -dot-  -dot-  -dot- 
> >
> > I like these Ten Rules for Technical Communicators:
> >
> > http://jersblog.com/Ten+rules.htm
> >
> > Disclaimer: The fact that I wrote them may have some bearing on my
fondness
> > for them....
>
> From that link:
>
> > You are the advocate for the end user. Everything you do is ultimately
> > for the end user. Sometimes your client needs a gentle reminder -- 
> > "That's an interesting suggestion, but how does it help the end user?"
>
> No. Good writing is not about activism for users. This is an idiotic
concept
> that has been infecting writers for too long. Where did you ever get the
idea
> that the users need advocates?

This is refreshing.  If users worked half as hard at understanding as I do
at documenting, they'd be my teammates instead of clients.  Still and all,
the audience is the prime mover of my efforts, because their information
needs are what defines the scope of my project.  "Advocacy" is an
unfortunate choice of words to describe the brand of
persistence/analysis/spadework that gets the information the end user
want/need.  Advocacy is even less fortunate, IMHO, as a descriptor of the
interpersonal and writing skills that yield usable written information.

Advocacy, to me, implies an adversarial environment, where the users have
run up against their limitations in getting what is rightfully owed to them.
They turn to a professional who knows how to navigate the system and
litigate to a settlement.  This is a fanciful notion, not the literal modus
operandi in most tech writing assignments. "Advocacy" is a hackneyed
expression, and flies wide of the bull's eye scored by writers whose efforts
are at understanding the product requirements and solution design,  and
shaping it in writing for the audience.

True, some of us do fawn over the audience, making our writing work an
homage to the belief that any information can be presented clearly.  Some of
us even get passionate about it, turning every assignment into a personal
sacrifice, hoping to attract the eyes of the muses.  But "advocacy" is
becoming yet-another-overwrought word that needs to spend a decade or two
gathering dust (along with "impact", and "leverage").

> Furthermore, tech writers are not the defacto user experience experts. If
you
> don't know how a product works or understand the people using it - then
> pointing out things you don't understand isn't "user advocacy" its
annoying.

The flip side is that tech writers are burn-out candidates when they're
constantly under pressure to find a working mental model of stuph that is
beyond their grasp.  The cognitive dissonance brought on by the demands for
articulate presentations, of things not understood, makes it as difficult as
learning to talk while being deaf.  Its bad stress for the writer, bad
outcomes for the project team, and we've all been through it (more than
once), I'll wager.

> Many technologies are designed and built based on specific market needs
and
> wants. If you want to get into user design, then become a desginer or
marketing
> slug. Don't assume because you can use FrameMaker, you're now entitled to
begin
> questioning the design of a product or technology.

I want to hedge:  Questioning the design is pretty advanced stuff, but the
writer is entitled to exercise judgement and curiousity in choosing which
chunks of information to bite off.  The real requirement, to my mind, is
that a tech writer has to be cool if the design seems questionable.  An
object lesson and true story follows:

On a project documentation assignment, I sat down to interview the lead
software architect and developer.  The developer led off with 5 minutes of
technical questions, directed to me, assessing my grasp of object oriented
programming concepts  Wow, I got my wish--a group that really wanted a
techwriting team member!  Though I had to shift from careful
listener/student mode to CORBA/COM lecturer mode on the spot, I passed their
test, and the architect sailed into a 20 minute solo presentation of his
view of their application.  At one point hw mentionedthat there was an
Oracle database built into it, and I braced myself , and plotted a course
through the dozen or so obvious questions  that I might expect to need
answers for, about the database.

When my turn came to ask questions, I launched my first probe on the subject
of the database.  The architect waved me off, explaining that the database
was no big deal, as it contained only two records.  Two records?  I blurted
it out.  "Why add the overhead of a database to the application?  Wouldn't a
named pipe or flat file be better, for a lot of reasons?"  Stunned silence
followed.  Heh.  For a second there I thought I was on the beam with a
penetrating insight, but the silence was key to a new understanding.
Assessing the damage, I glanced over at the lead developer, who had been
absently studying the empty table in front of him. Now he was animated and
friendly in delivering to me what I felt must have been the same answer he
had gotten when he questioned the need.  "The data is relational."  His
animation dissipated as he said it, and I was left staring at two
poker-faced team players.  The telegraph was humming, reminding me that
their decision process and commitment to the design were a done deal, as any
fool would assume from the outset, so why had I just stepped in it with both
feet?  The entire two weeks I lasted on that project was exactly like
that--from the moment I questioned things, they questioned me and my
judgement.  The fact that I knew my stuph and had a plan for the
documentation didn't weigh in heavily enough to balance the effect of my
presumptuous question in that first meeting.  As it turned out, they already
had doubts about contract tech writers--there had one before me (his seat
was still warm when I was hired) that they made the scapegoat for slow
documentation progress.  That writer later told me they had spent months
goping around and coming up with endless weak design decisions.  They needed
scapegoats to blame for the slow progress, and I was next in line if I
exposed a thin hide, which I did, and so I was.  That was the end of that
little object lesson.

But the hedge.  The hedge is in the bottom line, which is that product
design is something the writer has to digest if any gaps are apparent in the
information provided by the SMEs.  I find that this gap condition is a
chronic condition in engineering tech writing, because the experts (by
definition) have great difficulty articulating what they know, at a level
the end users can use.  I would expect the engineers or SMEs to respond in
good humor to good questions, even if I appear to be taking a bite of the
design apple.  Its not a sin, it just costs more (I assume a budget of
roughly $25 per half hour interview time, with typical simple information
questions costing 50 cents each (e.g., the name of the database costs $.50),
and a design question costsing upwards from $10 each).

As a post-grad in the school of hard knocks, I have changed my research
techniques, and now do a lot of boning up before interviews, and perhaps
most importantly, I submit my questions to the SME in advance. If there's
budget left over and the SME has by-passed any design questions I submitted,
I quite likely will angle for an answer to them, but I'm ready to grovel and
scrape and shake hands and thank them for a productive interview.

>
> Yes, I know....Some places will allow the tech writers to become a part of
the
> design and development process. But this is usually after they have proven
they
> have expertise with the technologies and industry. Its not something you
get on
> day one.
>
> Andrew Plato
>

Ned Bedinger
Ed Wordsmith Technical Communications





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l 

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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
http://www.raycomm.com/techwhirl/ for more resources and info.