Designing Software for a New Product: Specification by Example

A goldfish can understand software product development processes better than a human being. It’s not a joke – human attention span decreased in the last few years from 12 seconds to 8. That’s how long we can focus on a single thing before we get distracted by something else. It’s less than a goldfish. Throw ambiguity to the mix and you have a concept that is hard to understand. Unless you use ‘Specification by example’ method.

As humans, we love practical examples. This allows us to communicate better, with a clear picture in mind. Examples that are easy to visualize help us define goals, requirements, specifications. IT is a -fast-paced environment. Everything has its place in a sprint and has to be done right the first time around. By using Specification by example (SBE), we are delivering quality to our clients.

What is a specification by example?

It’s also known as acceptance test-driven development (ATDD or A-TDD), Agile Acceptance Testing (AAT) or Test-Driven Requirements (TDR). The term itself was coined by Martin Fowler in 2004, although the earliest usage of the idea was made by Ward Cunningham in 1996. The values, good practices, and principles of SBE however, were thought by Kent Beck in 1999. The key idea behind it comes in the form of single source of truth (SSOT). It’s a good practice in which all structuring information and all associated data are stored once and referenced by links only. That way business analyst, software product developers, and software delivery manager have their work cut out for them.

By using specification by example, every software product development company can make products smoother and without usual annoyances. When business analysts use their own documentation, software product development team uses their own one, alongside with quality assurance specialists with their set, everything can blow up in your face. Obviously, you don’t want that. That’s why it’s a good idea to think about ourselves as goldfish – not necessarily human beings with attention deficit disorder but as busy people with no time to lose.

Specification by example integrates key ideas:

• Workshops for clarification of requirements
• Concurrent engineering
• Tests as requirements and requirements as tests
• Prevention instead of detection

It’s all about:

• Deriving the scope of the project from its objectives
• A functional pathway to support the process. Business objectives, then deriving the scope, then the creation of the stories.
• Collaborative specification of requirements
• Illustrating with examples
• Automation of specifications
• Frequent validation

Deriving the scope. The key is always to understand the client. His business needs, technological issues and most importantly – why he or she needs the software in the first place. A software product development company has to ask a lot of questions. Software development partner needs to understand everything that drives the client; that also includes market conditions.

A functional pathway. By creating practical user stories based on business objectives, a software product development team can imagine scenarios of real-life usage. The more specified business goals, the more realistic user stories, the more accurate and useful functionalities in the end.

Collaborative specification of requirements. The entire team should participate in this one, including a quality assurance specialist and the client. The language should not be technical, you want everyone to get involved and understand each other. Use workshops! A face-to-face conversation is always better than documentation. After all, it’s Agile! It will speed up the process; rapid application development is everything.

Illustrating with examples. Avoid numbers, fancy words, technical phrases and everything else that might disrupt the message. A good example is precise (explains the context and system’s behaviour in each case), complete (from the initial idea to planned results), realistic (takes into account real-life situations and a tendency to misuse the application), easy to understand (you should not feel the obligation to explain anything to anyone). It’s very important to add UX/UI at this stage, to call out potential problems and underline solutions.

Automation of specifications. There are tools out there to help you out with automation. Software like Cucumber or Cradle will do the job.

Frequent validation. Enable continuous integration process for effective testing. It’s much more efficient than automated testing. By performing regular tests, you make sure the code is in line with business needs. Run tests after every change to guarantee quality and performance.

When to use specification by example?

When your project suffers from domain complexity or when your team has problems understanding requirements. Finally, when a software product development team, the client or the business analyst fail to communicate requirements from the business perspective to the rest of the team.

Use any technical equipment. Computers, TV and other tools will help you understand what’s most important. Talk, communicate. Use Agile techniques during the workshops to fully immerse yourself in the situation. We often meet with clients, but most of our work is done from Poland. It’s called “software product development offshoring” for a reason. Understanding our customers is critical; that’s why we use techniques and methods to help us out. Specification by example is one of them.

The method at CSHARK

At CSHARK, specification by example is performed according to the described frameworks in diagrams.

As specification by example requires a collaborative approach to define business needs, and then, requirements, we need some common understanding for end-users, developers, and testers.

This common artefact that serves as a single point of truth and understanding is usually a user story. User story allows these stakeholders to understand business goals, understand the problem and produce a solution which best fits the business need. It usually consists of three parts: card, conversation, and confirmation. The card is usually either a piece of paper placed on board or a virtual sticky note put on the board by the help of specialized software like JIRA or TFS. Such a card allows keeping the focus on involved parties in the development of this feature onto the card. The second part which is the card front usually consists of a key element, which is the business need that needs to be fulfilled. This must be always expressed in business language, not a technical one. Commonly a well-defined user story needs to define a role, goal/benefit and reason (why). Once defined, we can also annotate other details to the story, like a further conversation with the customer, diagrams explaining the problem, or mockups. Such content allows the software development team to decompose this need to tasks and find such a technical solution that will satisfy the goal of end-user.

The back of the user story, called confirmation needs to be filled in with acceptance criteria. They are indispensable to verify if the technical solution designed by the development team really fulfils its goal. Again, these acceptance criteria are not tested scripts but will be used to expand into test scripts and scenarios by testers during the sprint. During recent times, behaviour-driven development techniques are employed to define test cases. They follow the scheme of <given…>, <when…>, <then…> Such a schema allows to reuse this template for test automation by many tools that use this Gherkin style of traceability between a user story and test cases.

All in all, this workflow finally evolves into living documentation where all involved parties like product owner, developers and tester can collaboratively work, reuse defined contents on the user story and expand upon during the implementation of feature or testing phase. Collaborative working and the common understanding is indispensable to deliver features. And specification by example is one of these approaches to achieve it.

In the end, it’s all about the business goal and the client.