22 July 2017

An example failure

There is a problem I see when people write features. We all know, examples are powerful. They can make an explanation come to life in the mind of a reader. But, I too often see features written with the examples, but no explanations. Let us assume you are teaching someone how powers work in mathematics.

You would first explain what a power is:

Given a numberWhen I calculate a power of this numberThen it is multiplied by itself the power number of times to get the answer

Then you would insert examples:

Given the number <number>When I calculate it to the power <power>Then <number> is multiplied by itself the <power> number of times to get <answer>Examples: | number | power | answer || 2 | 2 | 4 || 3 | 5 | 243 |

More often than not, the explanation behind the examples is missing:

Given the number <number>When I calculate it to the power <power>Then I get the answer <answer>Examples:| number | power | answer || 2 | 2 | 4 || 3 | 5 | 243 |

The latter scenario does not explain the relation between the values in the examples, so how is someone supposed to write something that will work for values other than those given? You can't. Yes, in the earlier example you have to know what multiplication is, but that is a concept that would be explained elsewhere (no teacher would try to teach powers before teaching multiplication).

Remember, examples are concrete representations of a concept, but they are not the explanation of a conept in and of themselves.