RE: "Two-track" documentation

Subject: RE: "Two-track" documentation
From: "Susan W. Gallagher" <sgallagher -at- expersoft -dot- com>
To: TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>"
Date: Tue, 14 Dec 1999 13:39:17 -0800

One whirler, echoing the sentiments of many, wrote:
>Hmmm. Being technically accurate does not necessarily mean telling the
>user everything. It just means that what you have should be right,
>right? So, in your sort example, if you tell the user to click the SORT
>button, and there is no SORT button on the screen (because it is
>actually called ARRANGE or something), then you are not being
>technically accurate, technically.

Yabbut, I'm not saying that the instructions shouldn't be
accurate. Of course they should. If you need to click a
button with a certain name, then you need to click that

What I'm saying is that sometimes being completely and
totally technically accurate in the details, particularly
in what happens behind the curtain when the user clicks
that button, is not necessarily the best way to go --
depending on the user.

No, not just leaving info out -- really mis-stating the
truth. And I'm not saying that this is a common occurrence,
only that it sometimes happens. For example, I have worked
on many software packages where specific functionality has
been repurposed for various target audiences. A database
front-end can be an application development system for
programmers or an easy query tool for end-users. Likewise,
a version control system can be a programmers cm tool or
an end-user easy file management utility.

Given the two examples above, there were occasions where,
in the end-user products, the users' perception did not
exactly match the internal processing. Where that was the
case, we decided to reinforce the users' perception rather
than disclose the facts about internal processing. The
information we gave the user was incidental -- not critical
to product use -- and technically inaccurate (i.e., wrong).

"That's not what happens, but that's what it looks like,
and the user doesn't really need to know otherwise."

In the docs that were targeted at programmers, we told
exactly what was going on in the processing end because
the audience needed to know and were capable of under-

Yup. I'm 'fessing up. I have deliberately, with the buy-in
of management, development, and the rest of the tech writing
team, introduced technical inaccuracies into documentation
in the interest of ease of use. It's happened maybe twice
in sixteen years. It may happen again, Idunno. I still
believe that it was the right decision to make, given the

So I'll say it again. Technical accuracy sometimes needs
to take a back seat to relevance and usability.

Never say never.

-Sue Gallagher
sgallagher -at- expersoft -dot- com

The _Guide_ is definitive.
Reality is frequently inaccurate. --Douglas Adams

Previous by Author: Re: "Two-track" documentation
Next by Author: RE: conditional text in Word
Previous by Thread: Re: "Two-track" documentation
Next by Thread: RE: "Two-track" documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads