[Date Prev][Date Next][Thread Prev][Thread Next][Author Index][Date Index][Thread Index]
- To: <xanatech>
- Subject: Documentation Proposal
- From: Marc Stiegler <marcs>
- Date: Wed, 7 Nov 90 08:57:34 PST
Well, the Time for Documentation is upon us. The obvious next
question is, "What do we document?" One part of the answer to
this is fairly algorithmic: we document the 1600 classes and
methods that are visible to the developer; or, we make those
classes and methods invisible.
Some, of course, must remain visible :-) So the next question
is, "What do we say about each class and method?" Now THAT'S
a harder question.
Herein is contained my proposal for what to say about each class
and method. This is intended to initiate a discussion, to collect
all the insights we have rumbling around, about what good documentation
At that point, having collected all the ideas, we will then make
a decision in the usual Xanadu style: the people actually writing
the documentation will use the ideas they consider good, reject
the others, and we will then get feedback from our first developers
(including the Montage team) about what's missing.
With that, here is Proposal Number 1, starting out with things
we DON'T need:
- Do NOT include the names of the programmers or the documenters.
If those names appear in the documentation, we will have much
less flexibility in routing questions to the most appropriate
individual, who may not be either the documenter or the original
programmer. We'll credit everyone in the document, of course,
but on a separate part of the document: this is one case where
high-precision links may not be an advantage :-)
- Do not document a method if the method's behavior is self
evident based on the rich, insightful discussion of the class.
This also applies, as per our discussion at the planning meeting,
to methods in a subclass which override methods in the superclass--in
general, the documentation of the method at the superclass correctly
explains the purpose and behavior of this method. Obviously,
if there is something special about a method, such as distinctive
errors or blasts, that should be documented.
- I have not yet thought of a reason to include a date with
the individual method/class documentation. Each time we release
this stuff, we will have a new date on the stack as a whole,
and a page which describes changes in the new edition. As nearly
as I can tell, that is sufficient. I am easy to convince otherwise,
Ok, it's nice to see a list of things we don't have to do, but
alas, we can't stop there :-) Things I think we DO need are:
- First, I'd love to see a well-written explanation of the PURPOSE
of each object. Tell me, as you write, "Why does this object
exist?" Too much of the documentation I have seen in my life
is of the variety:
A = A + 1; (* Increment A *)
Yes, we incremented A, but why?
I propose the following motto: "Ask WHY not once, but Twice."
Tell the reader why you incremented A, and then tell him why
you did the thing that was the reason for incrementing A. With
a class, explain why the class exists, and then explain why this
higher-level purpose exists. This will not always be easy, but
I think it will often be helpful; indeed, explaining these ladders
of abstraction may be a saving throw in the prevention of Xanashock.
- Next, include a discussion of the structure of the class,
sufficient so that the reader can construct an effective mental
model of this object.
- Put in a list of errors, and of blasts that you may have to
- Add a list of classes and/or methods that are frequently used
in conjunction with this object (looking at the method used to
end a session, you would want to list the method used to begin
a session as a reference--if you don't begin the session, the
end session will not work very meaningfully, if at all. This
is more important in less obvious cases, where you use an obscure
method to set up the conditions for an obvious method).
- Finally, if possible, include a 3-5 line example of the object
in use, which would interrelate the structure, the purpose, and
the related objects and methods: don't worry if you can't do
all three of these things in a single example :-)
That's all I believe is critical in creating this first
Part of the methodology in writing here needs to be keeping your
blinders on. Explaining one class will invoke a requirement for
the reader to understand two other classes and a couple of general
points that don't really belong with any particular class. Do
not get distracted or upset when this happens to you. Assume
the other classes will be documented later. Make a list of new
topics that need more general discussion, but do not try to address
them. Have faith, we will get back to it.
I predict this will be upsetting for some Xanadians. The first
few hundred classes you document will cause you to feverishly
add topics to the list of non-code topics that need to be explained.
The key to success was first elucidated by Douglas Adams: DON'T
PANIC. Keep your blinders on. Believe me: eventually the list
of additional topics will stop growing.
Remember that this is
very much how information pools will evolve in the future: people
will write snippets of explanations for snippets of the overall
system, then link them up, using the links as the backbone to
hold it all together. Get used to this style of writing--it's
the style we are going to make a standard :-)
In government contracting, documentation involves zillions of
items that must be explained for each routine, whether the item
is self evident or not, whether anyone would ever care or not.
If we complete just the purpose, the structure, the errors, and
an example for every class and method in the system, we will
have documentation more wonderful than most of the documentation
I've ever encountered.
What additions, subtractions, and alterations to this documentation
proposal do people recommend?