Two Oft-Forgotten Modelling Tips

  • architecture

Rendering advice about modelling is tricky. There is so much context and style wrapped up in it, that it can be hard to distill the cogent bits of wisdom. Regardless of the context, two mistakes I see crop up again and again are poor or missing legends and a lack of unified visual language.

Here are two oft-forgotten tips on legends and visual language from my upcoming book, Application Architecture for Developers:

1. Use a (Good) Legend

The first, most straightforward bit of advice on modelling that is left by the wayside far too often is this: include a legend. Whether you’re doing lines and boxes or full-blown standard UML, it behooves you to include a legend of visual terms. By being precise about what you mean, you remove any ambiguity about the visual language you’ve decided to use. This may go without saying, but a diagram without a legend is liable to be interpreted differently from what the author intended-by other team members, or even future-you.

Here is what I suggest for building a legend:

  1. The first step is to ignore the legend. Contradictory, I know, but you aren’t building a diagram so it can have a legend. You’re building a diagram to answer a question. Answer the question first, then nail down the visual language and legend later.
  2. Once you’ve solidified the visual language for your diagram, create a rectangle/container to house your legend.
  3. Copy one of each type of element in your diagram into the legend.
  4. Add a precisely worded label to each. Names are important, especially in a legend. An ambiguous legend can give your readers a faulty (and varying!) view of what’s what.
  5. Now that everything is right, align your legend visually to give it that doesn’t look like junk feel.

A final word, once you have a legend, don’t let it fall out of date. Whenever you add or modify elements to a diagram (your own, or others), adjust the legend to reflect the new state of the diagram by adding, removing, or updating elements.

A sample legend

2. Use a Simple Visual Language

More subtle than “use a legend” is this bit of advice: maintain a simple visual language within and across your diagrams and models. I say subtle because developing a visual lingua franca requires much more work and attention to detail then slapping together a legend. Boiling down to the basics and remaining consistent takes a lot of effort.

Why do it then? Simple. Maintaining a simple visual language lets consumers of models focus less on syntax and more on semantics. While it takes a bit more effort up front, it pays off in droves. Not only will you have an easier time communicating with your team, but you’ll likely save yourself some time in the future when you revisit the diagram. Once a visual language becomes the lingua franca, you and your team will be able to communicate effectively via diagrams. A picture is worth a thousand words… if you’re on the same wavelength.

This sounds a lot like some kind of unified modelling language (UML), no? UML is a good base to draw from, but it isn’t the be-all, end-all. A lingua franca is the common tongue between speakers of many dialects–UML is just one of those dialects. Aim for a low-friction middle ground between all of the members of your team. Use common UML elements as a base where possible, but deviate as need arises.

Some things to consider as you’re building a diagram:

  1. Vary the visual styling of an element to indicate properties. For example, in an Entity-relationship Diagram, use coloring to represent if an attribute is required or optional.
  2. Reduce a particular visual elements to represent only one concept or element. Don’t let the meaning of an element be dependant on context, it increases cognitive load necessary to interpret an element.
  3. Pay attention to the number of legend entries. A global lingua franca may be large, 10-20 items or more, but within the scope of a single diagram aim for 5-10. This isn’t a hard limit, but you may be building a model of everything if you need more than 10 elements of visual style. Models should focus on a small number of aspects or questions per diagram (ideally one question).

Like this post? Subscribe to my newsletter.

Get fresh content on Clojure, Architecture and Software Development, each and every week.