Understanding what "how it works" means

Subject: Understanding what "how it works" means
From: "Michael West" <mbwest -at- bigpond -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 27 Sep 2008 11:26:27 +1000

I was called into a discussion between a lead programmer and a manager from
corporate finance. My role was to help scope the user assistance requirement
for an enhancement to our accounting system that will support the submission
and approval of travel expense claims by company executives.

The following exchange ensued.

LP = Lead Programmer

AM = Accounting Manager

AM: [Looking at me.] The users will need to know how it works.

LP: No, they won't.

AM: Yes, they will.

LP: No, they won't

AM: Yes, they will.

LP: It's like when you buy a car. Do you need to know how it works?

AM: Yes, you do.

LP: No, you don't

AM: Yes, you do.

Me: The users will need a very high-level overview
of the whole process, plus details about what

THEY need to do to make it happen.

BOTH LP and AM, triumphantly: Yes, that's right!

They both felt vindicated. And they were both right. The problem was simply
that they had different ideas about what the "it" refers to in "how it
works". The Lead Programmer thought it meant "how the software works." He's
right--users don't need to know or care to know the engineering details. The
Accounting Manager thought it meant "how users perform their part of the

This sort of misunderstanding happens all the time. When someone says
"explain how it works", it is impossible to understand their intended
meaning without considering both the speaker and the audience. For a
technical audience, "how it works" means engineering details. For a business
audience, "how it works" means a how-to for users.

This is also why I have always disliked the word "documentation." Without
explicit modifiers and delimiters, the word is invariably accompanied by
confusion and misunderstanding. Too often, a load of useless verbiage,
padded out with pointless screen shots, gets fobbed off onto the users under
the label "documentation."


Mike West

Melbourne, Australia


ComponentOne Doc-To-Help gives you everything you need to author and
publish quality Help, Web, and print content. Perfect for technical
authors, developers, and policy writers. Download a FREE trial.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Previous by Author: RE: "Up with which I will not put" (was: RE: "and then, " or simply "then"?)
Next by Author: RE: Judge criticises Microsoft documentation
Previous by Thread: Re: Low cost online meeting space
Next by Thread: Judge criticises Microsoft documentation

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

Sponsored Ads