On Detailing Options

The Devil is in the… options

Pretend we’re sign writers commissioned to write a menu of milkshake flavours. We’ve received our instructions on a note.

The flavours are Strawberry, Chocolate, Banana and Vanilla.

After some painting we present the sign as we’ve understand the instructions.

Milkshake Flavours: Strawberry, Chocolate, Banana and Vanilla.

However milkshake shop owner is disappointed that the sign isn’t what they expected. As there appear to be only three options on the sign. After a discussion we realise our error, that the ‘and‘ between Banana and Chocolate could have been represented like this:

The flavours are Strawberry, Chocolate, Banana, and Vanilla.

Oxford Comma

The Oxford Commaimage sourced from: https://knowyourmeme.com/photos/946417-oxford-comma

As the saying goes, the medium is the message and given that the intent was written down the semantics of grammar notably: - Commas to denote participation in a group. - The conjugative effects of ‘and’.

However there are two very different to understand this representation of the intent.

I try to not be a pendant about many things but the presence of an Oxford Comma (aka. Serial Comma) in my experience creates clarity more-so than the absence thereof.

It’s a simple example that even when we believe we’re being reasonably specific, ambiguities can creep in.

Milkshake Flavours: Strawberry, Chocolate, Banana, Vanilla.

So how could we have done better?

Now while this is a trite example, as the concepts (thus the rules) of milkshakes is one most are familiar with. If we were detailing the large hadron collider, I know I would be out of my depth. I wouldn’t know any of the rules. So what are we to do?

Thankfully there are some heuristics to help us make better sense of our options.

Some heuristics for describing options

  • Mandatory, do I have to make a choice from the available options? Can I skip over the choice and still get a complete experience?
  • Cardinality, how many options can I have at a time? Is is limited to only one choice or can I have multiple choices?
  • Repetition, can I make multiple selections of a choice? For example chocolate compared to double chocolate?
  • Mutual Exclusivity, if I can have more than one option at at time, are there any combinations that are prohibited?
  • Equivalence, how similar are the options? If there is a great variance then perhaps we need to reconsider the way we’ve structured the “thing” we’re describing.

In summary

The articulation of intent informs the implementation, be it verbally or transcribed. Our prior knowledge of a domain will inform our attempts to control any ambiguity between intent and implementation.

However we don’t need to have domain knowledge to achieve clarity when tasked with communicating options. Rather there are some heuristics we can apply to tease out the details and achieve specificity.