Fog Creek Software
Discussion Board

Learning to communicate graphically

I have been coding in one form or another for many years, and  for almost all that time I've been doing so by myself. (Only programmer in small company, etc.) Now I'm working with other programmers taking a lead design and programming role and find it necessary to communicate graphically. Diagrams, flow charts, sequence diagrams, use cases -- whatever is needed to teach people about an existing system as well as talk about new design ideas.

Unfortunately, I've found that I'm quite bad at it. I tend to think in code rather than diagrams, and "know" relationships much better than I can explain them. I feel this is partly a brain wiring thing -- some people are simply better at expressing ideas graphically -- but also that with practice I could reach a useful level.

So the question then becomes: how? Have you used any resources that you've found helpful in how you think about this sort of graphical communication?

Chris Winters
Monday, April 29, 2002

Try "Drawing on the Right side of the brain".

Doug Withau
Monday, April 29, 2002

While Drawing on the Right Side of the brain is a wonderful book, I am not sure it is appropriate for this application.

UML is probably the most talked about from of code communication via picatures going.  I personally find it usefull, expecially Object diagrams, Use Cases, and Object diagrams, in that order.

There is a UML in a nutshell book from O'Reilly that will be handy.

Of course, all this implies an Object oriented Background. 

For Non OO diagraming, code is probably as good as flowcharts to communicate an idea.

Entity Relationship Diagrams are the standard for Database work.  UML will still help at the packaging level (which code blocks are within which DLL)

Monday, April 29, 2002

> whatever is needed to teach people about an existing system

There's a tool called _Understand for C++_ ( ) which can generate call stack pictures etc etc from existing code.

Christopher Wells
Monday, April 29, 2002

Whoa, back up. Before you use modeling tools, hit the whiteboard.

As you diagram, keep in mind
- what you're trying to comminucate
- who your audience is
- what level of detail and precision they need

My diagrams usually contain boxes for Things, and arrows for relationships or interactions. A thing is a class, a logical component, a service, whatever.  If a thing has other things, especially encapsulated things, I draw smaller boxes inside.  If the audience doesn't need to know about the smaller boxes, leave them out.  I label the arrows.

If you're trying to communicate two ideas, use two diagrams. You might use a simple one for an overview, then zoom in on a class and show more detail.

For algorithms and processes, I write out the steps in words along side it. 

If we're at the level of describing lines of code, it's more appropriate to open the file in an editor.

Once you've sketched out the rough draft, you can redraw it prettily with UML tools.  Like Powerpoint, you can waste a lot of time making the presentation tools bend to your will.

Is this too simplistic, Chris?  Perhaps you could give some examples of graphic communication gone wrong.

Monday, April 29, 2002

The "Drawing on the Right Side of the Brain" book looks intriguing -- I think part of my problem is that I never think about  or communicate ideas graphically, so that skill never gets exercised. A resource like that looks like it gets you in the mode and from there you can start bootstrapping into different types of graphical styles.

UML can be a good thing -- better than making it up as you go along! -- but I think part of my problem with UML is that for newbies the GUI tools are overwhelming. Best to start small and simple with a whiteboard or easel + paper. And don't be afraid to throw away something and start again :-)

BTW, I think the _UML Distilled_ book by Fowler and Scott does a pretty good job of introducing it in context.

tangram, your advice is the sort of thing I need -- it's not rocket science, but approach it much like coding: have an overall message, then break it down into smaller chunks which work together to do the job.

Chris Winters
Tuesday, April 30, 2002

Have you ever sketched a map to your house? If you can do that, you've got the basics down already.

I actually find it easier to explain things to non-technical people because it requires less precision and allows more use of metaphor. These diagrams tend to be more cartoonish.

For a text document, where I'm not there to wave hands and embellish the whiteboard, I tend to use more labels and accompanying explanations.

Tuesday, April 30, 2002

Shoulda been specific:  I hardly ever use UML tools.  All my UML is done on a whiteboard.

Although, you may want to think about drawing on white poster paper instead if it is a brain storming session.  Yes, you cannot now erase, but you can keep a copy for later discussions.  THose whiteboard capture things work wonderfully, I've been told.  Someone once suggested using a digital camera to capture the whiteboard at the end of the session.  That sounds like the best Idea yet.

The Fowler book is quite good, as is just about everything he has written.

Tuesday, April 30, 2002

My problem with UML is the way it is used in some shops, not UML itself. With it, they explain WHAT and HOW, but don't explain WHY. They think that UML is the silver bullet that will suddenly make software designs self-evident, and therefore better. Every tool, when not properly used, is dangerous. I've been to countless design overviews where some techy proudly shows his pretty diagrams and while looking at it I can't help but ask _why_, sometimes. So I tend to speak up and ask, why was this or that choice made in the first place. They give you a vitrolic look, I interpret that look as "are you dumb? don't you see it in the diagrams?". The fact is, I don't.

I find UML very helpful to graphically model patterns, relactionships and processes. But to be able to explain wider design choices you will have to be able to explain yourself graphically and accurately. There are a number of things I find useful when explaining something. Make a fair use of analogies, people might not be related to your system, but they might know about something that works in a similar way and they are more familiar with.

Exercise yourself by explaining simpler things, if you have a little one in the house, explain her how a water tap works or whatever. Kids are great because when they don't understand they'll pop up a question. Sometimes adults are too afraid to ask. Some adults prefer to walk away misinformed than to ask a question. That's why it's very important that when you explain something to a colleague you are accurate and know the subject VERY well.

Beka Pantone
Tuesday, April 30, 2002

From my wish list:

Thinking Visually: Business Applications of 14 Core Diagrams
by Malcolm, Phd Craig

I can't make any comment on the quality. I'd love for anyone who's read it to review it.

Wednesday, May 1, 2002

I suggest looking at Edward Tufte's three books, _The Visual Display of Quantitative Information_, _Envisioning Information_, and _Visual Explanations : Images and Quantities, Evidence and Narrative_.  Intelligently written, beautifully designed, and using examples from a range of disciplines, Tufte's books are the best books available on communicating information graphically.  These books are not written for technical professionals, but for anyone who creates or reads graphical information.

Tufte has his own web site, , which has information about his training seminar and his books, as well as a discussion group on information design.  I have not participated in the latter, so I can't speak to its quality.

Daniel S. Cohen
Thursday, May 2, 2002

Well, I can't say that it address the Why per se, but look at the Use case analysis diagrams.  That is where you model who uses the system and what they are trying to do.

Any new feature you come up with should be within the realm of a use case.  Either you are ijmplmeneting a new use case, or simplifying an existing one. 

There is a lot of confusion over the extends versus precedes/follows as far as use cases go.  Don't get wrapped up in that.  WHat I've found is to think Top down with use cases.  Example:  In ecommerce you'll have a shop use case, which is composed of a browse catalog, add to cart, and check out use cases.  Browser catalog must happen before add to cart.  Add to cart can lead to checkout or back to browse. etc.

I'll try a little ASCII art to convey this:

O                      |                                              \/
\/      --->(Browse catalog) -->(Add to cart)--> (Checkout)
/\                          /\              |                      |
Shopper                  |_________|_____________|
OK, that looks like crap, but maybe it will help.  a constraint on the top arrow specifying that you can only go to checkou if you have items in your cart might be in order.

Friday, May 3, 2002

Ugh, that posted worse than I thought.  Sorry.

Friday, May 3, 2002

*  Recent Topics

*  Fog Creek Home