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: documenting code From:"Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM> Date:Thu, 5 Nov 1998 14:26:17 -0800
Wouldn't you know -- I turn my back to go off on vacation and a subject
like this comes up! Hope I'm not too late to contribute to the discussion!
From what I've seen in the archives, those who've contributed to the
discussion before me have had good things to say, most importantly
that you need to determine the audience and purpose for the docs
before you begin. Certainly, your goals for API documents that will
be sold along with your company's object code to other software
vendors will be broader in scope than will your goals for internal
docs.
That said...
OO code is built hierarchically; that is, classes are built upon one
another and those that come later inherit behavior and attributes from
those that come before. Be sure to document the inheritance tree well.
An OO class can be divided into public and private sides -- the public
interface consists of the messages that objects of the class understand
and the information that can be retrieved using those messages. The
actual implementation -- the way in which objects of the class process
the received messages to arrive at the returned value -- is the private
side of the class. If you goal is API documentation aimed at programmers
in other companies, you need only document the public side of the class.
The principle of encapsulation stipulates that the sender of the message
has no interest in the internal processing that derives the return value.
If, however, you are documenting the implementation side for internal use,
you'll probably want to spend more time on the private side than the
public side of the class.
Back to the public side, the class interface...
For each message that an object of the class understands, include:
1. The way the message should be constructed (think of this as a
template for a line of code). In Java, this would normally take
the form of:
public return_type method_name (parameter, parameter)
2. Discuss the number and types of parameters including any
default values.
3. Discuss the returned value, if any, and include its data type.
4. List the conditions under which the message will fail and the
types and values of any "exceptions" that are "thrown" (error
messages returned).
For API docs, you'll need to construct some sort of user manual as well
as code reference. Conceptually, its an interesting challenge to construct
a task-based user manual for a programming language -- particularly if
you're not a programmer. Interview your SMEs with your hands on the key-
board and stop them when they wax poetic about how the code performs its
particular miracles. Concentrate on the ins and outs of the tasks at
hand -- for example, "Adding the WhatsItApp toolbar to your application's
main window" and "Passing data from your application into the WhatsItApp
chart-generation module".
Finally, don't let the task or the technology intimidate you, but recognize
that you've got a much different task and a much different audience on your
hands than you're used to. Don't be afraid of the terminology; resist the
urge to translate programming terms into lowest-common-denominator English;
and put up with the passive voice when it's necessary.
