Guest Post by

Product specification – the seven biggest mistakes

When you’re developing products, it might become clear shortly after the first phase of the euphoria of rapid prototyping that you and your team can no longer keep track of everything that you have decided along the way. As long as the scope of the features and the team are still small, that’s not a problem. When in doubt, you can just have another decision meeting and hope that everything comes out the same again, and that you don’t squander too much time. But if your team gets bigger, if the range of functions expands, if the product becomes more durable, or if parts of it are outsourced, then at least a description of the product features will make you feel good. If you haven’t got your act together yet and have neglected the description of your product like before, then it really goes downhill. But really, you don’t have to write anything down, as the next seven stories show.

Agile is great because you don’t have to write anything down

We develop everything agile and value working software over comprehensive documentation – it says so in the agile manifesto. That is not really a direct recommendation to neglect all product documentation, but by exploiting the room for interpretation, it has definitely come to mean that. Mr. Sutherland said later in an interview that he wished he had formed this sentence more clearly and that unfortunately people were glad to have taken this as a way to thoughtlessly justify neglecting any product documentation, but he was already a bit older then and maybe he didn’t really understand what he was saying anymore.

Documentation with post-it notes does the trick!

Documentation with post-it notes does the trick!

Decisions are always forever

In principle, decisions for or against product features are forever. Once implemented, you have the inventory. That you will have to look back on it to see what you specified earlier (because you’re thinking about changing it) is yet another incorrectly interpreted fairy tale that might be applicable for bad product managers and product owners – but not for us. Moreover, it’s hard to revise a decision made about a product feature later on. That just shows that you made bad decisions earlier. And as a last resort, the source code is its own documentation. Reconstructing a product feature from 10 000 lines of Python is easily done!

Acceptance tests are better done by feeling than by features

Acceptance tests that slavishly go through the list of agreed-upon product features are a sign of mistrust. At the point of mistrust, the relationship to the contractor is already disrupted. We won’t let it come to that. Then a contractor won’t get the idea of wanting to lower the price or blame unsuccessful product features on others. It used to be like that, but in the meantime this this problem has been completely solved in modern organizations (and there is no longer any other sort).

Anyway, documentation doesn’t solve all problems

It is pretty well known that even the most careful documentation of product features can’t produce a common understanding. Doesn’t that essentially mean that its absence fulfils the same criteria? Clearly another point that shows that specification work has barely any value!

Why specify when you can just keep everything open?

Documented product features make you have to determine things far too early. Obligatory specification represses creativity in the team – which is a sign of structural violence – and a culture of fear is established and flexibility is rigorously prevented regarding the question of the problem the product should solve.

Performance specifications are annoying – modern external development works without them

Sooner or later it comes: the need to have parts of the product developed somewhere else. Because they can do it better. Or because there are no free resources at the moment. But stupidly they want to know so annoyingly exactly what they should do. And without a performance specifications, they don’t want to just make some set price offer. What an indulgent industry. Yeah, okay, then bill us for the days. It’s more expensive, but so what?

Colorful post-it notes are more useful

Thank God there are modern methods with which one can get around the extra work of specifications. Design thinking, for example. The exact idea of the product can also be kept without knowledge of the foundational societal technique of writing. You need at the most lots of different colourful post it notes, pens and people who want to draw little pictures and stick them to the wall. It doesn’t get more exact than that.


Jokes aside – there are lots of good reasons to write down product features in a specification. The essential ones are:

  • Products are complex. Too complex to just remember all the details.
  • The exact qualities of individual product features have to be available to all the different stakeholders (developers, testers) even if the product’s “inventor” can’t talk at that point.
  • Products are durable. And no one can remember complex concepts that were figured out by other people a few years ago.

But how much effort should one put into a product specification? It shouldn’t go in the direction of art for art’s sake. There is a rule of thumb that can be kept in mind to stay in the right direction: The more risk you’re willing to take, in the sense of the difference between desired and delivered product, the less specification. And vice versa: the more important it is to someone that something comes out exactly as desired, the more effort has to be put into the specifications.

Joachim Reinke has been a project manager for over ten years, both freelance and on staff. He also works as a trainer and coach for product definition and requirements management. Because he was also a programmer for many years earlier on, he also knows what it feels like to work on the receiving side of product specifications.

EN Subscribe to our newsletter
0 replies

This discussion is missing your voice.

Leave a Reply

Your email address will not be published.