RE: Benchmarking Technical Documentation

Subject: RE: Benchmarking Technical Documentation
From: "Kelly Williamson" <kwcwtech -at- iwaynet -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 25 Jul 2001 13:02:58 -0400

Jane wrote:
> If I am writing instructions on how to program the VCR or how to use
> voicemail on a phone, I don't *need* to know how the VCR works or
> how the phone works. (snip)
> I *do* need to know how the user will use that item of equipment or
> this piece of software.

And Andrew replied:
> No - you do *NEED* to know.
> Its a matter of evaluation. Even if you are not going to document
> exactly how something works, you need to comprehend the functions.
> This allows you to accurately evaluate the information you're
> presenting to the user.

I've seen Andrew make this point several times on this list, and while I am
a big fan of being technical and not just a page formatter, I totally
disagree with Andrew and agree with Jane on this point.

Andrew, how on earth does knowing the inner workings of a VCR help you write
a manual for a user that just wants to program it? If you're writing a User
Guide (not a programmer reference, etc.) how does knowing Visual Basic help
you communicate to the user what he needs to know about the *interface* and
how to use the software? I've created Programmer References before, and I
needed to look at the code to see what was going on. I just don't see how
that is even remotely useful for creating a user guide. You shouldn't need
to read the code to figure out what the interface is doing, any more than
you need to know how a VCR works to program the time on it, or how a watch
works to read the time. What you do need to do is test the software/product
and make sure it actually does what you think it's going to do. My last
project was a Web application. While I'm extremely competent with HTML, I
never once needed to look at the code to describe to the users how to use
the application.

I'm a non-believer at this point. Your point of view on this has always
stumped me. Feel free to try and convince.

/Kelly Williamson
Columbus, OH


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: Re: Benchmarking Technical Documentation
Next by Author: Re: Benchmarking Technical Documentation
Previous by Thread: RE: Benchmarking Technical Documentation
Next by Thread: RE: Benchmarking Technical Documentation


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


Sponsored Ads