(part of the Knowledge Curation series)

It’s a strange word to find in a modelling blog. We usually think about the ‘provenance‘ of an antique or a painting as telling us where it came from and something about it’s story.

So maybe it’s not so strange that we’d like to know the provenance of our model information:

  • Where did it come from?
  • Who has reviewed or approved it ?

..and most importantly..

  • why does it look the way it does ?

Think for a moment how you would explain a bit of your model to someone else, if you were both stood at the same whiteboard.

What you would NOT do is tell them to wait whilst you draw up a big diagram, than start to explain it all (see ‘Telling a Story’).

You’d draw a bit, explain a bit, and I expect you’d also be saying things like ‘we decided to do it this way because...’ or ‘..there are lots of ways to do this, and we chose this one because of ...”.

These are all statements about the provenance of the model. Not just explaining the ‘what there is‘ but more ‘why it is the way it is‘.

Now I’ve been modelling for more than 25 years, but as proof that ‘every day’s a school day’, a few months back I saw a brilliantly simple way to do this:

Design decisions example

The modeller wanted to remember WHY this component had these interfaces, so they created two ‘design decision’ elements to hold the explanation. And one of them is even linked to the part of the organisation which was involved with the decision.

Compare this with the alternative:

design decision no details Which one would you rather see?

Sure, there is a big overhead in writing down all these decisions, but imagine looking at this diagram in a few years time, when you’re thinking of re-using that component? Now which one would you like to see? It’s like having the original modeller stood next to you, ready to explain it all.


Capturing provenance has a potential impact on your model, so we need to think a little before doing this. Here are some suggested implementations ideas:

  • Decide on what a decision looks like (special kind of class, artifact or other – depends on what your modelling tool allows)
  • Make it look different from other stuff, so nobody thinks these are part of the model content
  • I also suggest linking them to other model elements using an obviously different line style/color, just to emphasize that these are just notes.
  • To encourage use of these ‘decision’ elements, how about giving special awards (buns, coffee) to modelers who add them to their models. More of them would get a higher quality score when the model is reviewed. A bit like comments in code (don’t get me started on that….)

About the Author Ian Mitchell

Ian Mitchell is a business analyst and software developer. He's been using UML since before it was UML, and has managed teams of BAs all over the place. He also teaches UML and BPMN, and writes the eaDocX document generator for the Sparx EA tool.
%d bloggers like this: