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:Inline Documentation, Part I From:Vignes Gerard M <gmv0570 -at- UCS -dot- USL -dot- EDU> Date:Tue, 13 Apr 1993 12:59:40 GMT
Inline Documentation, Part I
Defining the Audience
Many programmers resent having to add inline comments to their code
and, like beginning composition-students, fail to grasp some of the
most essential concepts upon which excellent (and rewarding) writing
is based. One of those key concepts is that of audience: the "who?"
and "why?" which dominates all literature, be it poetic or technical.
(1) Who reads inline documentation (coding comments) anyway?
Well, the audience is almost certainly:
(b) experienced with computers and programming,
(c) and probably interested in performing one of:
(i) porting the code to a new platform,
(ii) fixing problems which may have been present all along,
(iii) or extending the functionality of the original code.
(2) So... what do they already know about the code?
It's a safe bet they already know:
(a) what the code is supposed to do from a user's perspective,
(b) what inputs are expected,
(c) and what output will be generated.
(3) What do they need to know then???
In order to perform the kinds of maintenance described in 1.c,
the audience will need to know:
(a) how the code actually does what it is supposed to do,
(b) where it does whatever it does,
(c) and what assumptions were made that might not hold if:
(i) the platform were changed,
(ii) errors were still present in the code,
(iii) or the functionality were extended.
(4) Can we converse with them like adults, or should we painstakingly
describe *everything* to them, like children?
(a) Remember that the audience is almost certainly limited
to experienced programmers and novices looking for new
challenges, and they would not be digging around in the
source code unless they were familiar with (or trying to
become familiar with) the environment.
(b) Furthermore, programming environments (language + system)
have at least one set of conventions and, unless one has been
adhered to, the reader will have great difficulty following
what is going on---even with the most effective inline
documentation which has yet to be imagined.
(c) But no programmer approaches a maintenance task without some
notion of what algorithms might have been used and how they
could have been implemented, and these expectations must be
used as the basis for determining which features to emphasize
and which to gloss over.
(d) And it is these environmental-conventions plus an anticipation
of what the reader may expect as a reasonable set of solutions
that determines what should be spelled out and what can be
In summary, don't waste the reader's time by elaborating on that
which might have been expected, and don't create confusion by failing
to adequately explain unusual or important features.
University of Southwestern Louisiana
USL P.O. Box 42709
Lafayette, Louisiana 70504