Explaining the General with a Specific

‘General to Specific’ is just the process which I’m sure you would do if you had to explain a complicated bit of a model, and if you could get your audience gathered around a white board. You’d just draw them an example.

Well-read readers will recognize this instantly as an example of the ‘Gang of Four’ composite pattern (this is what made me into a modelling geek – just this diagram, presented by Kent Beck at IBM team meeting in the early 1990s – happy days).

Students of UML will understand what this means, but it’s beauty and utility as a solution to an organisation hierarchy problem are not immediately obvious. So I’ll read it back to you:

1. There’s an abstract idea of ‘Organisational Unit’ (abstract because it’s in italics – my least favorite bit of UML notation)
2. There are two ‘real’ types of things which are kinds of Organisational Unit: Person, and Team.  These are shown by the lines with the arrow.
3. Teams are slightly different from People: they can contain other Organisational Units (the line with  diamond). But People can’t.
4. And because Organisational Units are either People or Teams, then Teams can contain Teams, which contain other Teams etc, until finally they contain People.

Simple, elegant, brilliant, re-usable in lots of ways, but really not obvious to anyone but a competent UML reader.

Other Applications

The example above uses a Domain Model: a model of the ‘ideas’ in someones’ world. But we might equally apply it to other kinds of model:

• In a Use Case (or User story), replace the generic with the specific. So
  “The use case starts when the user wants to find a widget configuration
  1- The User tells the system the widget details
  2 – the System finds matching Widgets, and shows then in order of configuration date”
  becomes:
  ” Fred needs to find the configuration of a type 45, blue widget
  1- Fred types ‘type=45, color=blue” into the system
  2 – system shows him:
  Widget   Type   colour        configuration date
  #123        42       blue                           1/1/2019
  #456        42       light blue             31/12/2018
• For a requirement, make a concrete example of the consequences of it:
  “The solution shall allow only pre-configured widgets to be listed”
  add:
  “…so, for example, un-configured – but pending – widgets will not appear”
  Is the second bit part of the formal specification? No. because we put “..for example…”

The key to using this technique is not just to scribble it on a whiteboard. It’s to include these example in the model, so that when anyone reads a document, or looks at a website which is based on your model, they will see your explanation.

Negatives

• It’s going to take some time to do this, so use the technique only where there are complicated bits. After a while, your readers will need fewer and fewer examples, as they start to understand what you’re saying
• Some pedants may confuse the specific with the generic, so make sure examples are clearly labelled as examples, and so are not thought of as part of the specification.