In most organizations, software development is split between two groups — product management and engineering. Product management is focused on building the right system. This requires product managers to meet with users, try and understand their needs, and develop solutions that meet those needs. To actually develop the solution, product managers must involve engineers who are focused on building the system right — writing the code, making it stable, and supporting it in production. Unfortunately, there exists an uncomfortable gap between product managers and engineers that forces the product manager to explain features in terms that an engineer can implement, and that forces the engineers to explain technological constraints to product managers in terms that a product manager can understand. To bridge this gap requires careful and considerate communication. It requires empathy from both product managers and engineers.

empathy — [em-puh-thee]

The ability to understand and share the feelings of another.

— Oxford English Dictionary

Building empathy between product management and engineering is a communication problem and requires each side to meet the other half way. Product management and engineering naturally have an information asymmetry between them based on their roles, training, and past experiences. Without a process for dealing with this asymmetry, what tends to happen is the description of what to build is pushed down into informal conversations, team meetings, and ad-hoc, undocumented decisions that are baked directly into code. The moment that someone leaves the company, or a developer is moved to a different project, much of that institutional knowledge is lost, providing an excellent opportunity for confusion, misunderstanding, and re-work.

One way to deal with this information asymmetry is to eliminate implicit assumptions by using a tool that helps keep everyone on the same page. Thankfully, there is such a tool — specifications. Yes, specifications.

Those of us that have done waterfall-style software development may cringe at the thought of software specifications — vivid nightmares of 100 page documents that are obsoleted by the first line of code. Others may have been swayed by the agile development rallying cry and eschew anything related to upfront planning. These feelings are not without merit — yet they don’t mean specifications are not useful. With agile development, the specifications are written directly into the code, which is generally preferred by developers. With up-front specification, the specifications exist in a Word document, which is generally preferred by product managers. A great tool for bridging the communication gap should meet somewhere in the middle by combining both the product management and engineering viewpoints to provide a collaborative environment for writing software requirements. Done well, specifications enable product managers and engineers to communicate with empathy — helping both groups really understand how the software they are developing.

One example of light-weight specifications that I’ve been experimenting with Specification by Example, which redefines the distinction between analysis, design, and implementation. With Specification by Example, specifications are written out as example user scenarios in a ubiquitous language that both business stakeholders and developers agree on and understand.

What’s interesting with specification by example is that it forces product managers and engineers to have a conversation in enough detail that forces explicit understanding. Over time, these conversations will help everyone on the team develop an understanding of the intricacies of the product, the users, and the deliverables. The specifications can also be used to automate tests, the tests describe — in accurate and plain language — the system as it exists. This description becomes the most powerful feature of specification by example — living documentation that is always accurate and understandable.

I’m just getting started learning about Specification by Example and have found it to be an excellent way of describing software in business-friendly language. Over time, I hope to use this method to help drive software projects from conception to completion. I’ll post an update with anything I learn along the way. Interested in learning more about Specification by Example? There are a few good resources available: