Patch Your Product Spec

I regularly observe in product teams that product specifications¹ are either never updated after v1 or don’t exist in the first place. The product backlog isn’t a spec, but rather a collection of intentions. But these intentions don’t have any formal foundation. There is something that changes everything: once you see user stories as product spec patches, you can begin managing your product properly.

Intentions meet reality

Most product teams are motivated to create and maintain a product spec in the founding weeks, especially for greenfield products. But after a while, reality hits and the once shiny Confluence doc never sees an update. Deadlines, bug fixing, features, and maintenance compete for team capacity and usually win against documentation.

This isn’t laziness. The team and stakeholders see documentation as a sidecar, appendix or side artifact. Automated testing was in this seat a few decades ago. Documentation (and automated testing in the past) was never part of the delivery workflow.

Once you add documentation to your Definition of Done, it becomes natural for the team to account for it. It’s easier to make time for it, because it’s part of the estimation in the first place. Delivery is only complete when the spec accounts for every change.

As soon as specs are stale, they pose a risk: during discovery and refinement, you can’t rely on them. During customer support, they are not helpful. As a paper trail for commitments, they are misleading.

Treat user stories as product spec patches

As a former developer, I am familiar with version control (think Git). It’s not just a backup of code, but also a paper trail for changes and a way for all contributors to see exactly which parts of the code base are affected by a certain change.

You need to understand the foundations of version control, most specifically pull requests, to get behind this idea: user stories are patches. And the code base that needs that patch is the product spec.

Adopting this philosophy makes documentation surgically accurate. This leads me to the following: spec-driven design, the principle of defining the spec changeset before implementation. Make it part of your Definition of Ready. Proper specification makes it easy for the product team to prepare and deliver product changes, since they have a full picture of the current state and how the change affects it holistically.

The bug-or-feature test

A nice side effect of spec/documentation discipline: you never have discussions about whether a change counts as a bug or as a feature. An up-to-date spec answers this immediately:

• If the requested behaviour is not defined in the spec, it’s a new feature/enhancement.
• If the current behaviour deviates from the spec, it is a bug.

With a thin or non-existent spec, almost nothing qualifies as a bug. That’s because nobody knows whether the current situation is deliberate or an accident. Even if you dig through past releases to investigate related user stories, how can you tell they reflect the whole picture?

Stop patching into a void

User stories become even more effective and valuable for the whole product life cycle when they change the product spec. A live product spec is a document every contributor actually reads, shares and relies on. It also remains a document people want to keep current. Don’t mistake completeness for bloat. Thoroughness eliminates uncertainty.

In my experience managing digital trust and identity products classified as critical national infrastructure, guessing isn’t an option. Negligence causes serious consequences. Maintaining a product spec, among other documents, is required by EU regulation. Does that mean I will stop expecting thorough documentation when I enter less regulated software industries? Absolutely not. The mandate taught me the significance of this investment by force. A good product spec pays off regularly during the product life cycle and isn’t served exclusively to auditors. Remember the risks of stale specifications to see the value of current documentation: More efficient refinements, informed customer support, increased clarity.

In practice

I recommend three mechanisms to get this going in your workflows. I stay tool-agnostic deliberately.

• Add spec impact section in user stories: Your Definition of Ready needs to require this before implementation starts.
• Make spec sections addressable with IDs (´REGISTER-DOI-01´): This makes referencing them easy and user stories queryable.
• Merge at Definition of Done: When the story gets delivered, the product team or you needs to insert the spec impact section directly into the spec document.

Touching on costs

A complete understanding of every aspect of the product is required anyway. A product that the product team doesn’t fully understand can’t succeed. Expectations and delivery would often not match. Onboarding new colleagues to the team often results in sentences like “I can’t explain it right now, I need to look into the code” without any follow-up. Answering the same questions individually, over and over, is annoying and wasteful.

You don’t save time by not documenting. The constant uncertainty about your product is regularly paid for with informal, unplanned and unaccounted efforts nobody tracks. Making thorough documenation part of the product development workflow doesn’t increase effort or costs; it just makes something that is present anyway visible and transparent.