Re: Technical Accuracy (was Employment Interview)

[Mark Baker <mbaker -at- OMNIMARK -dot- COM>]

Chuck Melikian wrote:
>
>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.

And a distinction I did not make. I made a distinction between functional
accuracy (that which causes people to act correctly) and philosophical
accuracy (that which causes people to understand correctly). If you like,
think of it as two different definitions of technical accuracy. (And the
distinction has nothing to do with level of detail.)

Is something more technically accurate because it causes people to act
correctly (whether or not they understand) or because it makes them
understand correctly (whether or not they can perform)?

Some might argue that this is a false distinction and that if you understand
correctly, you will always act correctly. This does not always prove to be
the case.

For instance, in the OmniMark programming language, all single value data
objects (variables) are in fact multi-value objects with a single value.
However, telling people this often leads to them using multi-value objects
incorrectly (they declare a one-value object where they should declare a
zero-value object, and then when they add values they have a bogus first
value). So in the documentation we are now treating simple variables as
different from multi-value objects, which is not philosophically accurate,
but hopefully will lead to better performance.

Now some may object, "but if they *really* understood they wouldn't make
that mistake". But achieving a real and complete understanding of a complex
product takes a lot of time and experience. Users need to be productive much
sooner than that.

And with well designed products, complete understanding is usually
unnecessary. We have GUI's on our computers so that we don't have to
understand how they actually work. (Files aren't really stored in folders on
your hard disk.) All too often, documentation falls into the trap of
explaining the metaphor when the metaphor was created to make the
explanation unnecessary. There are any number of true facts that you can
state about a product which do nothing more than confuse the user.

On the other hand, it is not only possible, but common, to say thing which
are philosophically inaccurate but which lead to correct action. The idea
that paragraph formatting is "stored" in the paragraph marker in Word is
often repeated, and it helps people to act correctly with the program, but
it isn't true. The paragraph marker is a screen representation of the end of
a paragraph, not a storage device. The truth about Word's file format is
quite different.

The fact of the matter is that, with most complex products we work with
metaphors, simplified models and picture truths, not with
philosophical-technical truth. These simple models let us get to work
quicker, even though they are not fully accurate.

So: Our information must be technically accurate in the sense that it causes
the user to act correctly.

The reason for making such a fuss about this point is that in technical
writing, as in most other fields, it is common to slip into measuring the
quality of our work not by its primary characteristics but by its secondary
characteristics.

The primary characteristic of a good technical document is that is causes
the user to act correctly in as short a time as possible. Unfortunately is
is expensive and time consuming to test for that characteristic.

If we look at several documents that possess the primary characteristic we
can observe all kinds of secondary characteristics: they use a legible font,
they have few spelling mistakes, they are written in clear simple prose.
These characteristics are much easier to measure and much easier to achieve
consistently. So we substitute them as measures of quality.

But they are not measures of quality, they are only correlatives of quality.
If does not necessarily follow that any document that uses clear simple
prose, has few spelling mistakes, and uses a legible font will cause the
reader to act correctly in short time. And it does not follow that a
document which is free from technical error will cause the reader to act
correctly in a short period of time.

Whatever other measures of quality we may use day to day, we must
subordinate them all, sacrifice them all, if necessary, to achieving the
primary goal of technical documentation: causing users to act correctly in
the shortest time possible.

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