[plt-scheme] Diagrams

I should make it clear I'm biased, and as Greg's experience
shows UML (or other graphical notations) can be helpful in
the right context.  I find

  list := null
        ! (cons elt list)

to be more concise and understandable than the
corresponding UML, but no doubt others with different
backgrounds would disagree.  The one time I did produce UML
was for due diligence, so we had to produce pages of junk
to give the investors the impression we were producing good
stuff (rather than spending the time actually producing
said good stuff; hmmm).

If I had to produce documentation for future programmers
I'd aim for:

  - a clear overall architecture
  - lots of examples

I'd ideally replace the examples with tests -- they're
runnable documentation and automatically tell you how up to
date they are.

Diagrams should help (in that something like a 1/3 of our
brain is devoted to vision), but I'm not sure of the best
way to use them.

HTH,
Noel

--- Gregory Woodhouse <gregory.woodhouse at sbcglobal.net>
wrote: 
> On Jan 16, 2006, at 10:40 AM, Richard Cleis wrote:
> 
> > ... I was merely hoping to  
> > produce something that wasn't a joke, this time.  Am I
> to conclude  
> > that diagrams have no place in programming or its
> management?
...

> I've used Visio (for UML) as a kind of a personal white
> board when  
> working on program design, and as a tool to facilitate
> communication  
> with others, and have found it very useful. 

Email: noelwelsh <at> yahoo <dot> com   noel <at> untyped <dot> com
AIM: noelhwelsh
Blogs: http://monospaced.blogspot.com/  http://www.untyped.com/untyping/

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com