Skip to content
July 2, 2010 / Ben Chun

Diagrams Should Be Helpful

I’ve been working on a lecture about servlets. If you don’t know exactly what they are, that’s to be excused. J2EE is not a super-popular web application framework, but it does have the advantage in this context of using Java. That’s because our students already somewhat know Java. So my job, in this lecture, is to connect what they already know to this new idea of servlets.

Searching around, I found a really nice UML sequence diagram that shows the relationship between a client, server, and servlet. I love these kinds of diagrams and there’s an easy way to make them. They’re nicely dense with information, and they’re a great way to describe a process. So I dropped the diagram into my slide deck at the appropriate spot, and thought I was good to go. Then I realized that I wanted to build up the concepts a little more slowly but still have diagrams along the way. After thinking about that, I remade the diagram in OmniGraffle, and exported different versions with increasing complexity to use at different points in the talk. I was pretty happy with that.

Then I tested the lecture by doing a trial run with one of my fellow instructors. He’s a computer science Ph.D student, so he was quite familiar with the UML sequence diagram. After listening to my talk, he pointed out that while this is a great way to show sequence information, there aren’t any complicated sequences here. So why introduce a more complicated type of diagram and require people to understand that each thing in the diagram has a lifetime represented by a vertical line? Why not just have a couple of boxes with arrows?

I mean, you tell me which is easier to understand. The UML sequence diagram:

Or the informal style:

This was a good reminder to me that the Rule of Least Power applies everywhere. Just because I am comfortable representing information in a particular way doesn’t mean that my students will be. There’s always a trade-off for having more power and flexibility. In this case, I’ll opt for simplicity. Back to remaking the diagrams.

One Comment

Leave a Comment
  1. Dad / Jul 3 2010 8:04 am

    Vote for informal style. Also look for the public restroom logo ON the door before looking above it

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: