Re: What should a documentation contain, and what not

From: Fons Rademakers (rdm@pcsalo.cern.ch)
Date: Mon Oct 18 1999 - 22:43:20 MEST


Hi Walter,

   I agree with your comments concerning the need for more extensive
descriptions of what methods are doing and the type of parameters
they take. The need for source should be only for extreme circumstances.
We hope to correct these problems in the future, but for the time being
our resources are still spread too thin. In the meanwhile, the FNAL team 
is making good progress providing tutorials.

Also we hope the recent discussion started on documentation systems
will lead to an improvement of our current solution.

Btw: lacking clear documentation does not violate principles of OO design.
It only violates the principle of clear and easy accessable information.


-- Fons


> Rene wrote:
> 
> > It is our experience that exposing the source has the big advantage
> > to show how classes are really used in the real life. I am not just
> > talking of the root source here.
> 
> I perfectly agree that a documentation should contain *example code*,
> best in the form of a tutorial to show the how classes are *used*. 
> 
> However, it should be a warning sign if one has to look into the
> *implementation* of a class to figure out what the interface is supposed
> to be, imho this indicates that the documentation is too thin.
> 
> In this sense example code is an essential part of a documentation.
> On the other hand, considering the source code and thus the implementation
> an essential part of the user documentation violates quite a few of
> the principles of OO design.
> 
> 
> 			With best regards,	Walter
> 
> 
> --
> Walter F.J. Mueller   Mail:  W.F.J.Mueller@gsi.de
> GSI,  Abteilung KP3   Phone: +49-6159-71-2766
> D-64291 Darmstadt     FAX:   +49-6159-71-2989
> WWW:   http://www-kp3.gsi.de/www/kp3/people/mueller.html
> PGP:   http://www-kp3.gsi.de/~mueller/pgp.shtml
> 


-- 
Org:    CERN, European Laboratory for Particle Physics.
Mail:   1211 Geneve 23, Switzerland
E-Mail: Fons.Rademakers@cern.ch              Phone: +41 22 7679248
WWW:    http://root.cern.ch/~rdm/            Fax:   +41 22 7677910



This archive was generated by hypermail 2b29 : Tue Jan 04 2000 - 00:43:41 MET