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.