Best Practices - Specification by Example - Weekly Sharing

Summary : "Specification by Example" is a collaborative approach where Product Managers, Developers, and Testers create requirements through practical examples, resulting in a living document. This method enhances quality and efficiency in agile transformations, often improving quality by over 50% and reducing bugs. The article outlines the stages of implementation, benefits, and practical cases, emphasizing its effectiveness in streamlining the development process.

Definition

Specification by Example involves the collaborative creation of requirements by the three roles - Product Managers, Developers, and Testers - culminating in a living document formed through practical examples. This approach serves as a structured methodology for requirements analysis.

During an agile transformation, if a team aims to enhance both quality and efficiency—particularly to achieve a significant boost in quality—adopting the practice of Specification by Example is essential.

Source of the Practice

"Specification by Example"
Practices in implementing Specification by Example

Why It Matters

Quality can improve by over 50%, and efficiency can increase by more than 10%, with the only investment required being training (typically 1.5 to 2 hours). Evidence shows that this improvement can be realized within just 1 to 5 iterations.
With Specification by Example, developers can also engage in testing, allowing testers to focus more on exploratory testing.
There's generally no need to organize PRD (Product Requirement Document) reviews, as PRDs are crafted in the format of Specification by Example.
The number of bugs identified during System Integration Testing (SIT) by testers tends to be minimal.

When to Use

The Specification by Example method is utilized during the collaborative creation of requirements. Within the Scrum framework, this typically occurs during the current iteration for the next iteration's requirements.

As the team advances in their agile journey, they can incorporate the collaboration on Specification by Example within the same iteration.

Source: Freepik

How to Use

1. Alternate Names for Specification by Example:

The following terms refer to the same concept:

Agile Acceptance Testing
Acceptance Test-Driven Development (ATDD)
Example-Driven Development
Story Testing
Behavior-Driven Development (BDD)
Instantiated Requirements Description

It's crucial to avoid redundantly introducing the same practice. For example, if one team member implements Specification by Example while another introduces ATDD (Acceptance Test Driven Development), it may create confusion and overlap.

Of course, this may conflict with the views of theoretical experts. While there may be subtle differences, pursuing those nuances in practice can incur significant costs and lead to potential failures.

2. Instance of Specification by Example:

The implementation of Specification by Example typically unfolds in two stages:

Basic Stage: The Manual Specification by Example phase, where instances are documented, and testing is performed manually.
Advanced Stage: The Automated Specification by Example phase, utilizing frameworks like Cucumber, with instances written in Gherkin language and tests conducted automatically.

Teams usually start with the manual phase before transitioning to automated testing.

Here’s an example of manual Specification by Example (using a user story):

1) User Story: Add Business Application Form

As an Equipment Administrator (WHO), I want to fill out a business application online for small network requests (WANT). So that the process is standardized and traceable, ensuring prompt communication of needs to relevant suppliers and area managers (WHY).

2) User Story Description

Users can initiate a business application by clicking the "Business Application" button, filling in the planned usage date, relevant area, requirement description, and application reason (the associated supplier information automatically populates after selecting the area). After submitting the form, the system automatically sends an email invitation to the supplier for an on-site inspection.

3) Instance Description

Customer Type	Operation Steps	Expected Result
Equipment Technician	Click "Business Application" in the navigation flow chart	1. Transition to the draft state of the business application form; 2. Default user information for the applicant, department, document editor, and modifier; 3. Default timestamps for document generation and modification; 4. Submission time is empty, and document status is "Not Submitted."
Equipment Technician	Click "Assigned Area" on the page	1. A pop-up shows all area information; 2. Double-clicking selects one entry, automatically displaying area manager, construction location, contact phone, email, and reference supplier information.
Equipment Technician	Click "OU Organization" on the page	A pop-up displays corresponding OU organization information; double-click to select one.
Equipment Technician	Click "Purchase Type" and "Planned Usage Date"	1. Displays all purchase types; 2. Time selection is date type only.
Equipment Technician	Enter "Application Reason" and "Requirement Description," exceeding 200 characters, and click "Save"	"Application Reason" and "Requirement Description" are highlighted in red, with the message: "Your input is too long; please keep descriptions under 200 characters."
Equipment Technician	Leave red * fields empty and click "Save"	Red * fields are highlighted in red, with the message: "This is a required field; please provide the necessary information."
Equipment Technician	Select one or more reference suppliers and click "Delete"	Corresponding reference suppliers are removed from the details.
Equipment Technician	Click the "Start Process" button	After process approval, area managers and corresponding reference suppliers receive invitation emails.

Source: Freepik

Outputs

The deliverables include a Specification by Example document (for the basic stage) and automated test scripts (for the advanced stage).

Case Study

The following examples come from a large enterprise:

After the EHS team implemented Specification by Example, quality improved by 75% within 3 iterations, stabilizing the average number of bugs per developer to below 2 in each iteration.
The Green Leaf team produced 22 functional bugs in one iteration before adopting Specification by Example; after implementation, the number of bugs dropped to 6 per iteration over 5 iterations.
The Wolf Warriors team, consisting of 4 developers, maintained a bug count not exceeding 13 per iteration over 7 consecutive iterations after adopting Specification by Example.