Home > Articles > Software Development & Management > Agile

Why Specification Workshops Work

Development teams have used specifications documents for years and produced many successful programs. Why change a system that works? Markus Gärtner, author of ATDD by Example: A Practical Guide to Acceptance Test-Driven Development, explains why specification workshops produce better results. Gathering the right people and asking the right questions can help you to develop the right product.
Like this article? We recommend

On a traditional technical project, the specifications document holds the results of a communication between the project stakeholder(s) and the requirements team. Most people are surprised to learn that the document approach leads to suboptimal results. Agile user stories and "specification by example" replace traditional requirements documents with a placeholder for communication and a specification workshop in which the team identifies testable examples for their work. But where is the difference between traditional requirements elicitation and how an Agile team trawls requirements in such a collaborative session? To answer that question, it seems we have to take a closer look at philosophy and epistemology.

Types of Communication

In his book Tacit and Explicit Knowledge, Harry Collins identifies five conditions [1] under which communication takes place:

  1. In the simplest condition, a message passed between sender and receiver leads directly to the transfer of knowledge. This simple situation in condition 1 requires no message changes or extensions; each party understands the other without any further negotiation.
  2. Condition 2 requires a little more work; the message must be transformed to be understood. For example, when you use a mobile device to read a novel, you don't understand the electrical signals directly. The display presents a transformed version of the digital book so that you can understand the information it contains. This direct transformation of the message doesn't extend or shorten it.
  3. When communication cannot be achieved under conditions 1 and 2, the message must be enriched, creating condition 3. For example, showing someone a diagram of the acceptance test-driven development (ATDD) cycle might fail to deliver the message of how it works, whereas a book on the topic might transfer that knowledge effectively.
  4. The traditional specifications document provides another example. During a requirements-gathering workshop, business users communicate their tacit product desires to members of the product-development team, who then write out an extended version of this message in a specifications document for the full development team to use.

  5. Sometimes all of the aforementioned conditions still fail to transfer knowledge. Condition 4 communication relies on the transfer of a message plus a fixed physical change on the receiving end of the communication, such as rewiring the recipient's brain. Think back to when you learned how to ride a bicycle. One of your parents probably coached you through the experience of balancing your body on the bike. With feedback, over time, eventually you discovered the limitations of bike balancing—you stopped falling off, and instead began moving forward.
  6. The final condition for knowledge transfer, condition 5 consists of the message plus a flexible and responsive physical change from the receiver. For example, in a social context, young people must eventually begin breaking free from the rules they have previously learned from adults, applying contextual knowledge as they discover how to behave appropriately within their own social circles.
  7. Let's consider a more extreme example. Suppose we bring an electric dishwasher to a native tribe that has never been exposed to modern civilization. To begin making use of this new tool, they would (at minimum) need to learn what "dishes" are and what electricity is, and they would have to understand the concept of a flowing water supply. For the "message" of the dishwasher—the knowledge of automatic dishwashing—to reach these folks, we would certainly need to do more than simply coach them with rules of how best to load the dishwasher for effective cleaning. A shift in the basic paradigms underlying this culture would be necessary as well.

What Is a Specification Workshop?

Let's take a closer look at what a specification workshop is, in order to understand what types of communication take place there, and why they actually exceed traditional requirements-gathering. A specification workshop typically involves at least three different specialists:

  • Customer or product owner
  • Programmer
  • Testing expert

You can run such a workshop with just these three people, or you can have a formal meeting. In either case, these three roles bring different expertise to the table:

  • Customers have tacit knowledge about the business, how it currently works, and how in the future the software may help them to do their work more efficiently. End users know how they want to use the software, what steps are currently involved in the procedure, and the particular underlying rules for their work.
  • Programmers have tacit knowledge about how the program code is constructed at the moment, what design alternatives are possible for upcoming features, and what sorts of currently implemented rules might contradict those for the future.
  • Testers know about some of the limitations of the system from the past, as well as some details about the currently implemented business rules. They also bring critical thinking to the table—the ability to see where one rule might contradict another, or where part of the system needs to change alongside a feature currently under discussion among the team. Testers, it seems, know that things can be different, and they follow up on that knowledge.

In a specification workshop, the team discusses any upcoming implementations for the next one to three iterations of the product. Programmers and testers raise any open questions about how they should realize the business rules. They identify gaps and derive acceptance criteria, so they'll know when the particular feature is potentially shippable. Customers clarify how they work as well as rules and principles they hold as tacit knowledge, and they help the team to come up with examples for anything they discuss.

Communication in a Specification Workshop

As we've discussed it in this article so far, a specification workshop doesn't seem to be very different from a traditional requirements-gathering workshop. What happens in a specification workshop with regard to communication and making tacit knowledge explicit?

First, when all the team members directly understand a feature or a story, they can agree to move forward to the next story. This is an instance of condition 1 communication: The message is directly understood, without any transformations or modifications. (Ideally, the team and the product owner already have sorted out such features before the workshop even started.)

Any team member who doesn't understand a feature completely will ask questions about it. The business representative will answer these questions in one of two ways:

  • He paraphrases the story, transforming the message (condition 2 communication in Collins' model). By changing the wording, the business representative transforms the team's understanding of the feature. If they get the message, the meeting can move forward to the next feature. If not, they might try other conditions for communication.
  • He answers questions to elaborate on the problematic feature. By using longer, more detailed messages, he can clarify his understanding of the feature more effectively—condition 3 communication. Through this elaboration, the team might be able to identify specific examples from the business flow.
  • But clarifying open questions might also lead to a rewiring of team members' neurons. This fulfills condition 4 in Collins' model. The message can be understood by transferring the context of the business rules to the team. This might take the form of insights into how the customer and end user currently fulfill their jobs. (This is why working with the customer for some time helps the whole team to deliver the right product—referring to condition 5 communication in the model.)

But Collins also talks about the concept of mimeomorphic and polimorphic actions. Mimeomorphic actions, when executed repeatedly, always lead to the same behavior. Polimorphic actions might be executed with many different behaviors, according to their social context. Also, according to the social context of the behavior, different actions might be necessary. In a specification workshop, the business side and the implementation side identify mimeomorphic actions that a particular feature will automate. The examples that the team identifies are examples of such mimeomorphic actions, which a computer can repeat over and over.

Think about a bread-baking machine. Polimorphic actions include choosing the ingredients for a particular type of bread, developing different recipes, and making decisions regarding baking times. Once these polimorphic actions are settled, you can go to the supermarket and buy a prepackaged recipe for one flavor of bread. (Of course, selecting the right bread flavor is another polimorphic action.) Once you've programmed the timer on your bread-baking machine, filled in the ingredients, and pressed the start button, the machine automatically executes the mimeomorphic actions that bake the bread.

The same principle applies to software that we develop. To solve the problem for the customer, we need to identify mimeomorphic actions that the program can automate. If we identify mimeomorphic actions that can be used as examples for how the customer will work with the product, we're setting ourselves up to deliver a successful product. But we shouldn't forget the polimorphic actions that any real user of a product executes. Test automation helps with the mimeomorphic actions, but we'll be unpleasantly surprised if we rely only on test automation. Polimorphic actions need proper exploration of the software before we deliver it. As Michael Bolton puts it in his article "Acceptance Tests: Let's Change the Title, Too," passing all tests doesn't mean that we're ready to ship, but that we might be ready to do that. We'd better find out if we really are ready before we put the product in front of a real user. [2]

Specification Workshops Make Knowledge Explicit

Specification workshops may seem simple. Bring the right people to the table, discuss upcoming features, derive acceptance criteria, and implement them. Many teams start with this approach, and they clearly identify problems ahead of time. Whether or not you automate the examples you identify at these workshops, you'll enable communication under several of Collins' conditions, whereas a traditional requirements document might fail to deliver the message because it addresses only one of five ways of transferring knowledge. Many teams gain benefits just by holding specification workshops in first place.

In the light of epistemology, we realize the great benefit in holding these workshops. Specification workshops not only substitute for traditional requirements-gathering workshops, but go beyond them by making knowledge from the business representative explicit to the team, so that the team can make the right decisions later, when implementing features. They'll also be able to seek different approaches if they identify different mimeomorphic actions for upcoming features by starting from user goals.

At this point, the specification workshop brings a shared understanding of the business logic and the system. In sum, it helps the team to deliver the right product for business success.


[1] Harry Collins, Tacit and Explicit Knowledge. University of Chicago Press, 2010.

[2] Michael Bolton, "Acceptance Tests: Let's Change the Title, Too," 2010.

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information

To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.


Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.


If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information

Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.


This site is not directed to children under the age of 13.


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information

If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information

Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents

California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure

Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact

Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice

We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020