RE: In Search of a Class

Subject: RE: In Search of a Class
From: Gay Reed <greed -at- incode-inc -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 28 Mar 2000 12:39:43 -0600

Iain averred:
Source code is not a good basis for documentation. Would he suggest that
the an analysis of metallurgy involved in building a car would help the
driver find his way to the shops?

Software is generally used to perform some business task or other: the
documentation tells you how: the software does the spadework.

The source code is normally of no interest to the end user, so why waste
time with it?

I must interject my qualified disagreement. While I agree that source code
should not be the BASIS of documentation, it can be a source of valuable
information for the TW. As a case in point, in using various software I have
often found it frustrating to happen upon a disabled field or control that
clearly held the key to my successful completion of the task at hand only to
find no clues as to the secret handshake required to enable it. In my own
documentation efforts, I examine the code to learn the conditions under
which particular controls are enabled or disabled. This allows me to tell
the user WHY and WHEN a control is available or unavailable, circumventing
unnecessary frustration where possible.

Sure, I could ask a developer. However, I see at least three benefits of
laboring over the code myself: 1) I gain deeper insight into the inner
workings of the program (and often bump, serendipitously, into answers to
other questions). 2) I get precise answers to my questions. 3) I spare at
least a few minutes of the developer's time.

Gay Reed

Previous by Author: Re: Worthless Tech Comm Degrees
Next by Author: RE: HUMOR: Good Error Messages
Previous by Thread: Re: In Search of a Class
Next by Thread: Re: In Search of a Class

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

Sponsored Ads

Sponsored Ads