Understanding what "how it works" means

["Michael West" <mbwest -at- bigpond -dot- com>]

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

 

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.
http://www.componentone.com/DocToHelp/

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.