Write Better Examples

tl;dr

• Avoid using vague terms.
• Use real world data.
• Use real world examples.
• Stop writing scripts.
• Involve fewer people.

Overview

Example mapping is an effective way to clearly communicate new features or user stories to a team. When used effectively, examples are shortcuts through hours of conversations and long user scripts.

Everybody who works in the software industry should understand how to map out good examples of their work. It is an extra tool in a developer’s toolkit and it is necessary if you are in a position of leadership such as Product Owner or team lead.

A prime example of example mapping is in the Friends’ episode titles. Here are a few of them:

• "The One with the Blackout"
• "The One Where the Monkey Gets Away"
• "The One with a Chick and a Duck"

If you have seen these episodes, you know immediately what these titles describe. There is no need for a description or even a list of the characters. Because the title is written as an example, is good enough for us to understand what the episode is about.

There are many ways to create examples. I have gathered five helpful tips from my own experience which you can use.

Avoid using vague terms

You should use concrete examples as much as possible to illustrate the use cases. Take a step back from your example and ask yourself “Is this as specific as we can make it?”.

For example, if my customer is using my banking system, rather than saying

• Where the customer clicks the submit button more than once and receives an error message.

You should say

• Where the customer clicks the submit button twice and receives an error message.

Be specific

Narrowing down what is meant by ‘more than once’ helps us to get a clearer picture of the example. Furthermore, it increases a shared understanding in the team. It is very possible that the first example would give confusion as to whether a button should behave differently when it is clicked twice or one hundred times.

Represent an idea with a concrete example rather an abstract example.

Use real-world data

When creating examples, one should strive to create examples using real-world data. The difficulty in creating examples with made up data is that we run into strange situations where our real-world data does not align with our fictional data.

For example, I can create the following example with my fictional data in my banking system:

• Where my customer deposits $300 into their savings account.

The team would receive a shock when their customer contacts them angrily saying that they have not taken into account their customers who are using euros!

It is easy for examples to deviate from the product specification when we fake the data inside them. Something so simple as using dollar instead of euro can easily be resolved by understanding the real-world data.

Furthermore, if we are working on a “legacy” system and use fictional data in our examples, then we cannot know with any certainty that our made-up data will fit with the data the legacy system produces.

The changing rules and data structures of legacy systems means that using real data to drive our examples is key. A simply misunderstanding in the data can very likely result in an incorrect solution.

Use real-world examples

In the previous section, we spoke about using real-world data. Following on, we should use real-world examples also.

It is important when creating examples that we capture how the end customer will use this specification. By capturing how they will use it in an example, we are able to capture what the specification involves.

If, instead, we use fictional examples, then we are creating a “what if?” scenario. Rather than focusing on what the specification ought to look like, we focus on our imaginative conception of the idea. More often than not, this will be a false conception.

Let’s go back to our banking application.

• Where the user withdraws €20.50 from the bank’s machine.

This looks good, right?  But what happens when the bank calls us back saying that they do not give change from their machines and inputting a decimal point results in a major failure?

This could have been avoided by using the real example of how a user ought to withdraw money from the bank.

Get close to the customer

It is key in these scenarios that the teams creating the specification have close access to the customer. In reality, this can be very difficult.

Large companies often have a heavy buffer between the customer and developers. If this is the case for you, then your goal is to get close to the person who is close to the customer.

Often, there will be a team that are customer facing and take on their requirements. Introduce yourself to this team and communicate frequently with them. Once you are on good terms with this team or person, you may be able to suggest that you come on board for the next customer meeting.

Stop creating scripts

Here is an example of a script:

• Enter username & password
• Click login button
• Land on dashboard
• Go to search page
• Search for “12 Passat”
• Click on first result
• Click on ‘details’ tab
• Check that car price is present

Scripts are not examples. What we are describing here is the how, not the what. By prefacing the how with the what, we are ensuring that the how follows the what and not the other way around.

What we are creating and why we are creating it is more important at this stage of discussion than understanding exactly how we are going to achieve our goal.

Furthermore, from an example perspective, we should not care how our specification is implemented.

Scripts act as anti-patterns to examples. By using examples, we can cut out the majority of a script and get to what the script is describing.

Imagine that any given feature involves pages and pages of scripts in order to correctly describe it. Now imagine what we need to look at when one of our usability tests fail. We need to comb through too many words to find what we need or where it all went wrong.

By having scripts instead of examples, we create a murky idea of what we are implementing. By using examples, our communication with the reader is much more effective and allows us to cut out a lot of writing, thereby saving us energy and lots of time.

Brainstorm with fewer people

A common issue I encounter is when there are too many people in the room for us to have a meaningful conversation. It is rare that a room consists of people who are all interested in what everyone else has to say. Most often, a subset of dominant personalities will take over the workshop and drown out the good ideas of the others.

There is a simple way to mitigate the amount of opinions in the room – reduce the number of opinions.

There may be those of you that think that having many opinions in the same room can be a good thing, and you are correct!

Very often, in order to hammer out the finer details of a user story or a feature, we need two or three strong-willed individuals to clash. In my experience, this type of conversation can be very helpful, but only if there is somebody to take charge and mitigate the conversations. This is usually the team lead’s duty.

Circular conversations

Doing workshops with large groups also increases the regularity of circular conversations. I believe circular conversations to be the most common time-waster in meetings.

By decreasing the number of persons in a workshop, we are able to take down everybody’s thoughts quickly with minimal time wasting.

At a very minimum, I suggest that three people are present in any one of these workshops.

• Product lead
• Test focused developer
• Developer

The product lead understands the product the best. This may be the product owner, team lead, or another stakeholder.

The test focused developer is important for their testing mindset. They need to be able to poke holes in what is discussed and find out where there are gaps in knowledge and understanding.

Finally, developer should be focused on understanding as much as possible from a developer’s perspective so that the how can be focused on later on.

Summary

Writing examples is a quick way to cut out needless conversation. Use examples regularly to save time and to increase communication between yourself and your team mates.

To summarise:

• Get specific - don’t use vague terms to describe your examples.
• What is actually happening? Use real world data.
• Who is doing what? Use real world examples.
• Save time - stop writing scripts.
• Circular conversations? Involve fewer people.