madhu@hubcap.clemson.edu (M a d h u Raman) (04/12/89)
Greetings: The powers that be ...want my code documented on "Paper". Other than spewing out a meaningless printout, any suggestions on documenting on "paper" so that the flavour of Smalltalk is not lost on the reader. With the browsers everything makes sense but how does one document the code on paper and still give the reader the same understanding ? Somebody must have tackled this problem about representation on paper. Any pointers or suggestions are most welcome. madhu@hubcap.clemson.edu !gatech!hubcap!madhu
rsimonian@x102c.harris-atd.com (Simonian RP 66449) (04/12/89)
In article <5078@hubcap.clemson.edu> madhu@hubcap.clemson.edu (M a d h u Raman) writes: > The powers that be ...want my code documented on >"Paper". Other than spewing out a meaningless printout, any suggestions >on documenting on "paper" so that the flavour of Smalltalk is not lost >on the reader. We have a contract for the Tri-Services (Army, Navy, AF) where we are implementing an Automated Knowledge Acquistion tool in Smalltalk using, believe it or not, full 2167 documentation standards. The standards are somewhat tailored, of course, but it's actually worked out quite well. If you are familiar with Government standards, we broke the system down into some high-level functional units (`CSCs'), such as the help system, the system monitor, and so on. Within each CSC, we followed the 2167 standards for inputs, outputs, sequencing, and processing. We are also providing class and method level details. I wrote a documentation generator (Smalltalk/V) which goes through a specified set of classes and dumps out class and method information in a readable format, as you might find in the Smalltalk/V reference manual. Part of its job is to pull out the first comment in a method. Richard P. Simonian 407/984-6006 Natural Language Processing Group Harris GISD, Melbourne, FL 32902 Internet: rsimonian%x102c@trantor.harris-atd.com
bwk@mbunix.mitre.org (Barry W. Kort) (04/13/89)
In article <5078@hubcap.clemson.edu> madhu@hubcap.clemson.edu (M a d h u Raman) writes: > The powers that be ...want my code documented on "Paper". Other than > spewing out a meaningless printout, any suggestions on documenting on > "paper" so that the flavour of Smalltalk is not lost on the reader. > > With the browsers everything makes sense but how does one document > the code on paper and still give the reader the same understanding? > Somebody must have tackled this problem about representation on paper. > Any pointers or suggestions are most welcome. Draw two diagrams. First draw an inheritance hierarchy diagram showing how the classes in your model are related with respect to inheritance from their superclasses. Then draw a decomposition hierarchy diagram showing how your overall model is composed from the classes. Show the key messages between classes as arcs in the decomposition diagram. Annotate your diagram with a few sentences explaining each class and each of the key messages. --Barry Kort
david@cullsj.UUCP (David Taylor) (04/22/89)
In article <1925@trantor.harris-atd.com>, rsimonian@x102c.harris-atd.com (Simonian RP 66449) writes: > We are also providing class and method level details. I wrote a documentation > generator (Smalltalk/V) which goes through a specified set of classes and > dumps out class and method information in a readable format, as you might > find in the Smalltalk/V reference manual. Part of its job is to pull out > the first comment in a method. Sounds handy. Is there any way of obtaining it?
JTangney@cup.portal.com (John Dominic Tangney) (04/24/89)
Ward Cunningham published a paper on documenting Smalltalk. See OOPSLA '87 Proceedings. Best of luck John T