Technically Accurate WAS:RE: Employment Interview

[Dick Gaskill <dickg -at- AG3D -dot- COM>]

Mark,

I am both an engineer and a writer/manager and have over 20 years of
combined engineering, writing, training, and support experience.
I am sorry, but I cannot agree with your opinion on engineer's vs
writer's versions of "technically correct".

"Technically correct" does not mean that you have to include every
minute detail of how something works, or every minor step a user must
complete to accomplish a task.  Technically correct means that the
information is factual and provides sufficient information for the user
to do what he wants/needs to do.  For example, most users know how to
operate a mouse; it is not necessary to spell out every step to use a
GUI.  If an instruction says, "Select xxxxx", it is technically correct.
The reviewing engineers do not come back with comments requesting a
change to "Move the cursor over xxx and press the left mouse button".

Nor do we go into detail when explaining the operation of the hardware.
The vast majority of my customers are engineers, and while managing
customer support (as well as pubs) I talked to thousands of them.   We
discussed the documentation as well as the hardware and software.  Not
one of them complained about the accuracy of the documentation or asked
for more detail because the instructions were not "technically correct".
In my experience, most engineers deal in facts, just as technical
writers do.  We don't go into long dissertations about the philosophy of
how something works unless it's absolutely necessary to use it.   If
your products require that much detail, a redesign might be in order.

I also cannot agree with your opinion regarding "getting an engineer to
read the documentation". The h/w and s/w engineers I work with are
required to review my department's documents AND sign off on them.  It
is not an option, it is part of their job description.  This is true at
nearly every company I have worked for, both big and small.   Further,
according to a survey I wrote while I was also managing support, 76% of
the end-users used the quick installation guide and 68% of them read at
least part of the users guide to install and/or configure the product.
And they are engineers.

Dick Gaskill
Manager, Technical Publications
AccelGraphics, Inc.

> ----------
> From:         Mark Baker[SMTP:mbaker -at- OMNIMARK -dot- COM]
> Reply To:     Mark Baker
> Sent:         Friday, February 20, 1998 4:04 PM
> To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject:      Re: Employment Interview
>
> Karen Kay wrote
>
>
> >I recently had an interview in which I was asked about conflicts and
> I
> >really had nothing to say. I've never had a serious conflict w/ an
> >SME. ...
> >So is this chance, or am I doing something right? I'd like to think
> >the latter of course. But I didn't get the job, for the very reason
> >you give:  I wasn't experienced enough in conflict w/ SMEs. This
> makes
> >no sense to me.
>
>
> and Dick Gaskill wrote
>
> >"Quality documentation is defined as accurate, appropriate,
> predictable,
> >readable, complete, usable, effective, and timely."
> >
> >accurate = the information is technically correct
>
> Which brings me to the reason you have to argue with SME's. The reason
> is
> <pause while I don asbestos underpants>: technical accuracy is
> irrelevant.
>
> User documentation is performance support material. Its purpose is to
> get
> users to act correctly. Whatever gets users to act correctly in as
> short a
> time as possible is what you should write **whether it is technically
> accurate or not**.
>
> Or, if you like, think of it as the distinction between functional
> accuracy
> (that which leads to correct action) and philosophical accuracy (that
> which
> leads to correct understanding). Philosophically accurate description
> of a
> complex product is usually dense and complex. If the product is well
> designed, a functionally accurate description is usually simple.
>
> Writers of user guides are in the business of functional truth.
> Engineers
> are in the business of philosophical truth. If you get your engineers
> to
> read your documents (argument # 1: they don't want to read them), they
> will
> not like them because they are not philosophically accurate (argument
> #2:
> they don't think they are accurate or complete).
>
> While some engineers can and do appreciate the need for functionally
> accurate docs, the majority don't get it unless you explain it
> (argument
> #3), and some don't get it even then. The stumbling block is that for
> most
> engineers there is no delta between philosophically accurate and
> functionally accurate (that's what makes them engineers).
>
> So, if you have never argued with an engineer, it has to be because
> you have
> been incredibly lucky with the engineers you have had to deal with, or
> because they have never read your documents, or because you have
> failed to
> create documents which are functionally accurate.
>
> Unfortunately, despite our increased emphasis on task based
> documentation,
> all too many tech writers still translate the spec into English,
> rather than
> describe the users task. Many still implement task based documentation
> by
> reordering material by task without actually changing it from
> describing the
> product to describing the task.
>
> Bottom line: your job is to make users act correctly, not to describe
> the
> product. Engineers don't like this and will argue with you. You have
> to win
> the argument or your users will suffer.
>
> ---
> Mark Baker
> Manager, Corporate Communications
> OmniMark Technologies Corporation
> 1400 Blair Place
> Gloucester, Ontario
> Canada, K1J 9B8
> Phone: 613-745-4242
> Fax: 613-745-5560
> Email mbaker -at- omnimark -dot- com
>
> ~~
> Send commands to listserv -at- listserv -dot- okstate -dot- edu (e.g., SIGNOFF
> TECHWR-L)
> Search archives at:
> http://listserv.okstate.edu/archives/techwr-l.html,
>
>