Perhaps a javadoc type tool could be written that generates documentation 
from the code
itself?  I'm not sure I understood your first example perfectly, but it 
sounded like a javadoc
type system might have solved the problem.  That is; yes if I have to go 
through methods
clicking links I would probably get confused, but if it generated web pages 
that correspond
to the methods and classes maybe it could work?

I mean as a first cut.  Of course at some point it would be nice to install 
a squeak app that
generates UML diagrams of the running system, lets you make code from there 
if you want,
get any kind of documented output you want.  But I think the javadoc thing 
could be done
really quick.


>From: Hans-Martin Mosner <hmm at heeg.de>
>Reply-To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>Subject: Re: Thoughts from an outsider
>Date: Thu, 31 Aug 2006 07:41:16 +0200
>
>Damien Pollet schrieb:
> > On 8/31/06, tim Rowledge <tim at rowledge.org> wrote:
> >> Another old friend of mine has also coined the rather nice idea of
> >> "program the document, don't document the program" to cover a concept
> >> of merging doc and code in the tools so that you can write spec,
> >> explanation, commentary, examples and limitations mixed in with
> >> executable code.
> >
> > Sure, literate programming is a nice idea but even if there is the
> > wonderful example of TeX to support it I'm not sure it's agile enough
> > in it's current form to be smalltalker-compliant :-)
>A long time ago, when I re-implemented a big chunk of TeX in VisualWorks
>to create a WYSIWYG TeX editor (WysiTeX), we tried to do something like
>literate programming in Smalltalk. My idea was that a Smalltalk literate
>program could not possibly have the form of a linear book, since
>Smalltalk programs are essentially not linear, so we tried to create a
>hyperlinked documentation (using a collaborative hypertext editor also
>written in VisualWorks). I was not really satisfied with the result - it
>did not have the close linkage to the code, and I don't think that an
>outsider would have been able to grok our code with the help of this doc
>bettern than without it.
>
>That said, I still feel that something like that would be needed. Since
>working with Objectory a number of years ago, I became enamoured with
>the idea of traceability - having explicit links between analysis,
>design and code. Objectory was a little too waterfallish, an agile tool
>would probably have to look a bit different, but still I think that a
>really good development environment should be able to keep all this
>information in one place, allowing me to create and follow links, to
>store document files, drawings, diagrams as well as runtime, building
>and test code in one place, with version history all over the place, too.
>
>I know that such a system would not help me much in writing better
>method comments (that's still a matter of discipline which I'm a bit
>lacking) but it would probably allow me to create overview documents
>which allow others to get into the code much more easily.
>
>Cheers,
>Hans-Martin
>