Enhance transparency. Specification by example in Jira!

Consider the following workflow:

  1. You develop a set of requirements and place them inside a Jira issue. If you work in an agile team, it might be a user story. 
  2. The Jira issue is handed off to the development team for implementation. 
  3. The development team implements the feature and notifies the QA team to test what they have coded. 
  4. The QA executes the tests using their own test scripts and finds that several edge cases aren’t covered. 
  5. The issue comes back to the development team with the request to add missing pieces. 
  6. They fix the problem and it passes the QA tests.
  7. The issue moves to the business analyst or product owner for acceptance testing. 
  8. It turns out that the acceptance tests documented, cover one more case that wasn’t implemented. 
  9. The issue goes back once again to the developers so that they can fill another software hole…


Sounds familiar? If it does, it likely means that your team is not working in the most effective way and they will benefit from introducing specification by example in their workflow.

Specification by example is a technique used in agile methodologies to define business requirements by illustrating them using realistic examples instead of abstract statements, such as user stories. 


Business requirement / User story

Specification by example

As a user, I can log-in to the application.

When I type “admin” in the username field and “secret” in the password field and click enter, I get logged-in to the application.


So, do I just replace all my business requirements and user stories with specification by example? 

No, not really. Both are useful but in different contexts and times. User stories are great for quickly capturing a new business requirement that arose during the sprint review, or customer interview, for instance. They are great when it comes to keeping the business requirements goal-oriented and at a high-level. However, the closer you get to actually implementing that idea, the more details you need. Acceptance criteria, test scripts, acceptance tests, and more. That’s when a specification by example comes to play and helps you reach the level of precision critical for the development team to successfully bring the idea to life.


Specification by example in Jira

With Jira, you can embrace the benefits of specification by example, which are: increased transparency and clarity in terms of who does what in the project.

Too often teams choose to track business requirements, development, and testing separately - a couple of Jira issues, spreadsheets, external tools, notes, and more. Everything scattered and impossible to find. Such a mess can be caused by various, trivial reasons such as lack of coordination, knowledge of tools, or being attached to a certain way of working. This leads the team to have details concerning a single feature in multiple places, which is certainly not healthy and does not contribute to the team working at their highest capacity. 

Instead, you can teach all of the involved parties to keep the details in a single place. It can be as simple as putting the user story, acceptance criteria, and test scripts directly in the description field of a single Jira issue and asking the team to use and update the requirements there. That way you ensure everyone is always on the same page and on top of all the updates that were made to any set of details. Moreover, you will avoid situations where the Jira issue bounces amongst the development team, QA, product owner, business analyst, and stakeholders, because they weren’t aware of all of the requirements beforehand. 

If you need more advanced tools that will additionally support the team, automate some of the work and provide more reporting, you can also browse the Atlassian Marketplace for apps that promote transparency and allow the implementation of the specification by example. Use one of the available checklists apps to track the Definition of Done and Acceptance Criteria directly in your Jira issues. Some of the test management tools also allow you to display the test scripts inside the Jira issues.


The above shows how you can utilize Multiple Checklists for Jira and QAlity Plus - Test Management for Jira from the Atlassian Marketplace to introduce specification by example.



Specification by example is a useful technique if you have several people involved in software development. It can save the team a lot of time on unnecessary rework caused by the lack of transparency. The technique does not replace user stories. It’s a way of providing implementation details that are needed when the issue is being refined. The crucial part is having everyone on the team keep the requirements and details in a single place so that no one misses any updates and changes. But the benefits of a single source of all knowledge go beyond merely informative perks. Team members getting easy access to a broader variety of project aspects can start discussions and bring their communication to the next level. Great ideas and even better solutions require productive dialog, no doubt. Making your Jira issue a platform for opinion exchange adds value and creates opportunities to come up with quality ideas on a daily basis.


Taranjeet Singh
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
September 1, 2020

@Sebastian Brudziński Nice article and very useful information on "Specification by example".

M Amine
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
September 29, 2020

@Sebastian Brudziński does Multiple Checklist manage attachment in the checklist? 

Sebastian Brudziński
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
September 29, 2020

@M Amineno, Multiple Checklists for Jira doesn't offer any additional management of attachments, despite what's already possible with Jira issue attachments.


Log in or Sign up to comment
AUG Leaders

Atlassian Community Events