Re: Documentation Proposal

[Greg Lutz <autodesk!alce!greg>]

>>>From autodesk!xanadu!marcs Wed Nov  7 10:57:30 1990
  >>
  >> - Do not document a method if the method's behavior is self 
  >>evident based on the rich, insightful discussion of the class.

And don't be like the slavish, tedious subroutine library reference
manuals one sees so often, in which everything is explained extremely
uniformly, and there is no admission that the description of the
current subject is perfectly obvious and derivable by any sentient
being from the description of another one, which duplicates 97% of the
prose in this one.  Or maybe DO be like such reference manuals.  But
say in the introduction just which you intend to be, and stick to it.
That way, the reader can infer information from what is omitted as well
as from what is written.

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

If followed all the way, such a ladder will lead up to "what is the
purpose of Xanadu".  On its way to that terminus, it will have merged
with various other ladders.  Duplicating the top 20 rungs in 1500 places
is obviously counterproductive.  However, there is probably merit in
SOME redundancy, i.e., overlap the ladders by a rung or two (I hope
we're not overworking this metaphor).  Since the intial cut of this
document won't be a Xanadu document, it will be necessary to decide
where to copy, where to refer, and where to do both.

  >> - Add a list of classes and/or methods that are frequently used 
  >>in conjunction with this object

Perhaps also mention other class/method families which exhibit a
strongly analogous relationship?  I mean, something more notable than
"this is the method which ends sessions started by method A, just as
method D ends sessions started by method C".  The question mark above
is because I don't know if this is  fruitful idea for Xanadu.

  >> - 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 :-)

Well, how big is the line buffer?