ASP.NET Security Consultant

I'm an author, speaker, and generally a the-way-we've-always-done-it-sucks security guy who specializes in web technologies and ASP.NET.

I'm a bit of a health nut too, having lost 50 pounds in 2019 and 2020. Check out my blog for weight loss tips!

Unclear specs? Maybe you need to stop writing specs.

Published on: 2015-01-11

I read a blog post recently from a company describing how their product can help developers be more productive. I thought it was fairly interesting in that it talked about creating better specs and creating prototypes to help everyone understand the problem being solved. But it suffered from one fundamental flaw:

In the most successful software projects that I've ever worked on, we didn't write any specifications at all.

If you work in traditional software environments, the idea that you wouldn't have business analysts writing specifications for the developers is probably quite shocking. But skipping specifications works so well that I'd be hard pressed, as a developer, to work from a spec again. How did we make it work?

Generally, the software architects were responsible for all leadership roles on the software team. In addition to deciding how the system would be built on the software side, they were also responsible for making sure that the software met the needs of the business, communicating status to all interested parties, and ensuring that the software met established time and budget goals. Someone serving as the product owner oversaw the entire process, setting priorities and making decisions on behalf of the user team. What are the advantages of this approach?

Less staff needed

The typical process to create software specifications is as follows:

  1. The product owner has an idea for a new change or feature and either writes up a summary or talks to a business analyst.
  2. The business analyst spends time to understand the business specifications, and gets clarification from the product owner as needed. Then the business analyst writes business specifications describing the changes desired for the software system.
  3. A senior developer or architect takes the business specifications and writes technical specifications describing in detail how the system should be changed to meet the business specifications.
  4. The developers take the time to understand the technical specifications and clarify issues with the architect and business analyst. The BA will go back to the product owner as necessary. The developers then implement a solution.

If the BA is an expert in both the business processes and technology, and if the developers truly cannot understand the business need, this process makes sense. Unfortunately, in my experience neither of these is true. BAs are rarely experts in technology and developers can understand the business need. Yes, by severely reducing or eliminating the BAs from this process, you put additional work and responsibility onto both the product owner and the developers. But if you reach a common understanding of what you are trying to accomplish and are flexible with the details, then BAs and specs typically get in the way.

Less rework needed

If there is one constant in life, it's that things will change. Changes in software occur because of misunderstandings, changes in business context, changes in management, additional features needed, and so forth. Writing code to be easily changeable is more difficult than writing code to meet the need at the moment. Therefore, being able to anticipate where changes might occur is key to making software easy to maintain in the future. When the development team understands the business, then anticipating change becomes relatively easy. When developers are limited to implementing technical specifications, anticipating change can be almost impossible.

Unleash creativity

Some of the best solutions I've created resulted from conversations between me and the product owner when we were just tossing around ideas - me from the point of view of what's possible and the product owner from the point of view of what's needed. Specifications can gum up this creative process. Both product owners and business analysts will unnecessarily simplify their requests in a well-meaning but misguided attempt to put the developers in a position to succeed, resulting in a subpar product.

Less miscommunication

The single biggest problem in communication is the illusion that it has taken place.
-George Bernard Shaw

The idea behind specifications, both business and technical, is to ensure that all interested parties have the same understanding of what is supposed to be created. Surprisingly, detailed technical specifications are often inadequate for this task. My best guess is that people, when presented with a large number of small details, fail to see the big picture. This results in software that may meet expectations but doesn't meet the business or customer needs.

What about testing?

Many people, when reading this post, would wonder how testing is done, since the business specifications are often given to the testing team to create test plans. Testing is like programming in that it's much harder to work with vague instructions, but if you have the right people in place, vague instructions result in much higher quality. I have not worked with testers much of my career, but most of my experience with testing teams is that when they have specific testing plans, they only test using those test plans. But users act in unexpected ways. Testing teams that are given free rein to think like the users find much more than testing teams who follow a test plan. Here again it is better to ask teams to accomplish a goal than finish a series of tasks.


Software efforts are the most successful when:

  1. The people who are building the software have direct access to the people using it and vice versa
  2. Everyone has the same big picture understanding of the problems being solved with the new software
  3. Effort spent on directly making the product better is maximized, while other activities are minimized

Writing specifications gets in the way of all three of these. If your developers are reasonably intelligent, then skipping writing formal specifications will improve your overall team productivity. If you have lower quality developers, or the product owners have little interest in being a part of the creation process, or you have a large team and need to keep everyone moving in the same direction, then specifications may be helpful. But don't create them just because by having them you are following best practices. In many situations, they are no longer needed.

This article was originally posted here and may have been edited for clarity.