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:

“As a user, I want to be able to annotate a dashboard with links, pictures and basic text formatting.”

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.

* Adding link and picture to an annotation widget
* Formatting text with bold, italic, underline

Design

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

* Switching the widget to edit mode by clicking on it
* Adding link, picture, format text with bold, italic, underline by entering some markdown markup

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.

* it switches to a textarea on click
* it saves text and switches to formatted text display on blur
* it changes mode to non-editable on blur
* it should automatically focus on textarea in edit mode
* it should format markdown text to html
* it supports multiple markdown features

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.

it(“should format markdown text to html”, () => {

mountComponent({text: “# test”})
const converted = fixture.querySelector(“.formatted-text”).innerHTML
expect(converted).to.equal(“<h1 id=\”test\”>test</h1>”)

})

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!