Re: Technical Accuracy (was Employment Interview)

[Chuck Melikian <chuckm -at- MDHOST -dot- CSE -dot- TEK -dot- COM>]

Mark Baker wrote:

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

He just pegged my bogosity meter. :-)

I think I understand what Mark is trying to say, but I cannot agree
with how it is written.

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

Just try to write a programmer's guide that is in any way technically
inaccurate! You will be shot on sight by the programmers for wasting
their time.

A programmer's guide is not "support" material. If the user doesn't have
the guide, they *will not* be able to program the product (in my company's
case, programmable test instrumentation). The user cannot "discover" the
programming commands the way they can discover how a drawing program
works under a graphical interface. For programming documentation, the
manual is as important as the instrument (or programming language),
because without the manual, the instrument (or language) is useless.

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

Describing exactly how to determine if a circuit board is working
correctly is absolutely essential. The description must be precise
 and it must be accurate. Saying that a circuit puts out a signal is
worth nothing if you don't describe exactly what that signal looks
like; the user cannot determine if the circuit is working correctly
if they don't know what a correct signal looks like. Telling a
technician a circuit puts out a square wave (technical accuracy) is
worthless unless you also tell her the voltage and timing charactertics
of the waveform (philosophical accuracy). The additional detail of why
the waveform looks as it does is not needed. I think what Mark is really
referring to is the appropriate level of detail needed not the "kind"
of accuracy.

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

I think what is being said here is describing the appropriate level
of detail, not whether a description is technically or philosophically
accurate. The truth is the truth. The level of detail provided may
vary, but whatever is said should be accurate. Period. "Technical" vs.
"philosophical" accuracy is a bogus distinction.

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

The documents I create are accurate. Period. I do not accept the false
distinction about kinds of accuracy.

And the engineers here may not always want to read the manuals (well, they
are engineers not writers) but they do read the manuals. It is part of
their job description.

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

Wow. I guess the engineers here are just weird. The last major new product
I worked on had engineers that spent a fair amount of time educating the
writers (it was a new market for us at the time) on how the instrument was
going to be used, not how it did what it did. They told us two years before
the product was introduced that they wanted task-oriented documentation.

As an engineering major, I don't understand how could anyone could design
a product that suited the customer's needs, if they didn't know what
tasks the customers needed to perform. The job of technical writers is
no different. The goal of a manual is to help the customer complete a
task, not teach them how the product does what it does.  Whatever we
write should be accurate.

Chuck Melikian                                     chuck -dot- melikian -at- tek -dot- com

Worldwide Customer Communications
Measurement Business Division
Tektronix, Inc.

   **Required disclaimer: These opinions don't represent the company
          I work for. (Though they probably should. :-) ). **