TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
button.
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-
standing.
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
circumstances.
So I'll say it again. Technical accuracy sometimes needs
to take a back seat to relevance and usability.
