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