How to Write Clean Cases and the Curse of the Minoans

We are what we write. From writing requirements and use-cases, user stories, test-cases, and code.

We could be digging for known problems or for exploring and learning. At the end of the day, case writing is a special form of storytelling. 

Effective storytelling is a major step towards effective problem-solving. To solve we must first achieve a basic level of understanding.

Understanding the basics is usually not enough and we must refine and deepen our understanding — this is where digging and explaining, both to ourselves as well as to others, comes in. It usually works in this order:

1. Understand the basics 
2. Explain
3. Solve

Clean cases can improve understanding and solving as we are about to see below.

Bugs

So there is a bug! At least it looks like it. We did a number of clicks during our journey in the UI and we’ve reached a point where we don’t see what we expect. But what did we really expect?

Hmm, we are not 100% sure. Why not? Because by the looks of it we’ve configured too many features to run at the same time. It’s difficult to understand how things should work in such settings. Imagine how difficult it will be to debug.

Knowledge Gaps? No Problem

Even if we don’t really understand how certain features work but we’ve found a crash, we better issue a bug and write clean cases. These are stories built progressively, explaining our interactions step-by-step. Stories with a clear beginning and ending. Whenever possible, they include only the relevant details.

General Problem Handling

When investigating a problem, in general, there are three possibilities:

1. We may know exactly the root cause
2. We may have a few ideas about it, some helpful and others not so helpful
3. Or we may be clueless

For all three possibilities, it’s good engineering practice to write (one or more) clean cases as a problem description. 

Writing Clean Cases

If we manage to reproduce a problematic behavior we could take the following steps:

1. Describe the testing environment (was it the production environment?)
2. Describe clearly your interactions with the system and their outcomes, step-by-step
3. Use multimedia and/or screenshots

Don’t just explain the final result. It’s challenging to go from the end result to the root cause without any clues. It’s how we arrived at the end result that will probably provide clues for causes and solutions.

Cannot be Reproduced Always? Make this Clear

If the problem is intermittent we should state so, including a rough estimate of a reproducibility

percentage. For example, out of ten tries, how many times was the problem reproduced? This percentage affects the overall impact of the problem.

It’s not Just About Words

A picture is equivalent to one thousand words. Similarly, a screen recording is equivalent to many thousands of words. It’s always a good idea to include screenshots and/or screen recordings in our clean cases.

The Curse of the Minoans

The Minoan civilization was a Bronze age Aegean civilization based on the island of Crete and other Aegean islands. Few mysteries and myths of the ancient world have captured people’s imagination like that of the Minotaur and his labyrinth. 

I recently saw a nice tv series called “Carte Postale” based on a novel by Victoria Hislop. In the first episode, a Cretan who had spent most of his life in a labyrinth of thoughts, sorrow, and ethical dilemmas, describes the curse of the Minoans: “They throw us in the labyrinth and if we don’t find our way out, we’re doomed”. Although his way out of his labyrinth had turned out to be a catastrophe, that sentence reminded me of rumors and stories about that so-called curse.

De-symbolising a Labyrinth

A labyrinth symbolizes complexity, since finding your way out of there is not an easy task. When telling a story, just because we mention how the story ends, it doesn’t mean that our readers will have a clear picture of what actually happened. Excluding useful information may create labyrinths.

For example, a bug report that mentions only the error message popping up in the end, could create labyrinths for the developers who attempt to fix it.

Our story is about a problem. Consequently, we should write it in a way that could help for a solution. Make it easy to follow and understand.

Craft it in a way that’s unambiguous, it avoids unnecessary details, focuses on what’s important and clearly provides the steps that need to be taken to reproduce the problem.

A Story is for an Audience

Keep in mind your audience. Above all, good stories are written when audiences are happy. For instance, no developer is happy when a labyrinth awaits.

As another example, no stakeholders are happy when a bug report does not clarify how to reproduce a problem. In addition, a single-step case may create multiple labyrinths. On the contrary, a very long case with dozens of steps may incorporate subproblems on top of other problems. Consequently, it may need to be broken into smaller cases so try to keep size to a balance, whenever possible.

Wrapping-up

To sum up, a clean case is a well-crafted problem description. It will help problem

solvers to avoid a labyrinth of thoughts. It will provide a starting point to solve the problem. And if a labyrinth cannot be avoided, the clean case may give clues to solve the problem and find our way out.