Home > Articles > Software Development & Management > Agile

Why Specification Workshops Work

  • Print
  • + Share This
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.
From the author of

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.

  • + Share This
  • 🔖 Save To Your Account