Some years ago I got a copy of HotDraw from Tektronix, and tried it out.
It was easy to run the examples, but I couldn't figure out how to make my
own.  Each method was easy to understand, but I couldn't figure how they
fit together, and their wasn't any documentation or comments in the code.
At the next OOPSLA, I asked WardCunningham how it worked, and he gave me
an hour CRC card talk.  It made sense, and when I got back home and had a
chance to look at HotDraw again, I could understand it and could make
applications with it.

If TheSourceCodeIsTheDesign, why couldn't I understand HotDraw when I
had the source code?  What happened to make me understand it?  The code
didn't change.  What changed?
-- RalphJohnson

''Look at that scenario as a specific case of this one: Someone hands you detailed schematics, not for a product but for an unbounded family of products.. each of whose design you can complete by customizing the schematics.  The schematics are modular, they have information that is localized enough for an implementer (compiler, woodworker, electrical tech) to make each portion and assemble them.  The schematics were also designed for ease of customization, but the aspects of the design which make customization easy are not labelled as such, or apparent in the schematics.  You can study to try to get a sense of it, but the schematics fill the needs of the implementors more easily than the customizers.  Designers make the schematics, but they communicate with other designers through ancillary documentation to the degree that their preplanned customization points are not apparent in the schematics.''

''I guess that XP is able to discard documentation because it does not consciously design in hooks for future customization? -- MichaelFeathers''

Michael has a good theory ... but it doesn't hold in this case. HotDraw was one of those rare programs that was designed to be extended everywhere. It did not having any explicit customization points. I only explained to Ralph how it did ordinary things. It's just that even ordinary things touched three or four or even more objects. Once Ralph could see this as a whole he figured out himself how he might change it. -- WardCunningham

I think Ralph raises a key point.  In fact new developers have difficulty understanding C3 until we do a few CRC sessions with them to tell them how things work.  As with Ralph's experience, it doesn't take many, but it takes more than zero.  I'm trying to set up an experiment with MartinFowler where we do a CRC session and then he helps us draw some very simple UML, to see whether we can use the drawing to transmit the info.

Also, one of the guys is going to experiment with Arbor's ADvance to draw some diagrams of the system.  Neither UML nor ADvance diagrams are part of XP, but experimenting with ways of communicating is.  I'll report results.  The tricky part will come in trying not to do too much.  These things can consume hours.  --RonJeffries

I have been enthusiatically embracing this promise of XP - that if we keep our code well-factored, we will not have to worry about maintaining our design artifacts (which go out-of-date very quickly), but I've been running into much the same problem.  It seems that YouNeedaGuide to begin to understand an unfamiliar set of classes.  Once you understand the basic structure, you can see how everything all hangs together, but without that structure, you are lost.

Of couse, this points us back to the original problem.  How do we maintain the documentation of that basic structure?  Is that the same as the SystemArchitecture?  --RussellGold

I think that CrcCard''''''s work because you can show a person how the objects interact with each other in a dynamic way.  ''(I also have my own suspicions about objects being understood by the right hemisphere of the brain.)''  A drawing can only show you a snapshot.  Could you explain the game of pool to someone using a picture of the balls neatly arranged in a triangle?  

The VcapsProject uses UML for the class hierarchy and an InstanceDiagram.  The InstanceDiagram gets used all the time.  Most of the cubes have one hanging on the wall.--DonWells