A common language for product specifications

Pipeline and deliverables

I like developing software products. I like the whole product development pipeline. My favourite workflow starts from product managers gathering what we call “user stories”, which we could define as a complete set of use cases to describe how to satisfy a need. These stories can be used to describe some deliverables or “epics” in task manager jargon, which will then be broken down further into bite-size tasks ready for the development team to work on.

A complete product development flow involves multiple people in interaction. Each stage of the process can sync-up by sharing specific deliverables. Typically, product managers will write down a set of user stories and feature lists, Designers will turn them into wireframes and flow diagrams, project managers will break the features down into tasks, etc. It can be hard to translate these documents across the pipeline. What if we could find a common language, so everybody can collaborate on building a shared vision of the product?

Let me share my experience using unit tests syntax to achieve this common operating picture.

User Story

A product manager collects user stories describing a user need. They are phrased in a way that doesn’t bother with design. For example “as a user, I want to click on a button” is not a user story. Here is an example:

Feature list

From these stories a product manager can translate it into a user task and a set of features that need to be there to accomplish it.

Design

A UX/UI designer can decide what actual UI elements and interaction patterns could be used to expose these features.

Unit tests specs

This level of specifications is where a lot of different people can collaborate since it’s the place to decide exactly how each features will be implemented. It may require sketching some UIs, revisiting some assumptions, maybe even getting back to the client. But once these specs are defined, everything should be clear.

Unit tests

The developer can then turn these specs into actual tests that will run against some code. The implementation details are coupled with the tech stack and not important here. But they rest on solid grounds, on a set of fine-grained specs validated by the whole team.

That’s it. I just wanted to show that the deliverables coming out of each stage of a development pipeline are not so different, but going from general to specifics, from a user need to a technical implementation. And the unit test specs can be a place where decisions are validated and everybody can sync around them, from product managers to designers to developers. Have fun unit testing!