Documentation Suggestion

Mike Rutenberg mdr at scn.org
Fri Sep 22 07:37:15 UTC 2000


My sense is that one of the problems causing our sporadic documentation
is that the existence (or lack) of documentation is not obviously
visible as you work with the system, either while browsing or making
changes.

By that I mean, you do not automatically see when a class is documented.
 Unless you explicitly go to the browser's documentation pane, or
explicitly pull up the network documentation (or even remember that it
exists), you don't know if there is nothing there for your efforts or it
is a rich wonderfully written description.  After a while I tend to stop
checking.

Making the existence of documentation more clear may help with this.

I took a cut at this with the simple change set I posted which annotates
the displayed class definition if there is no class comment.  It is just
a small gentle reminder, the goal being that if I am working on a class
I know well and I see that there is not a comment, I am likely to
quickly add one. (Date: 25 Aug 2000, Subject: [ENH] gentle encouragement
to add a class comment)

Mike

p.s. Other tools or presentations related to class information are also
imaginable.  The browser "?" could be grey if there is no documentation
and get more and more black bold as the class comment gets longer
(better?).  Or a class information window that runs in the background
and provides all kinds of information about the class most recently
selected by a browser.  Or a network-shared Q&A note space where people
can add their informal comments and questions about a class or
individual methods (this is similar to the suggested automatic comment
adding tools).





More information about the Squeak-dev mailing list