Documentation Proposal

[Marc Stiegler <marcs>]

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

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

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

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

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? 

--marcs