The Case Against Specification Documents

Every week, we welcome new clients who are eager to have Revelry work on their projects. Many new clients approach us with specification documents in hand. But each week, I see the ways that these documents distort projects and pull all of our efforts away from their true goals.

And I’m here on a mission of mercy.

I’m going to make the argument that specification documents are not the best way to make your software, and that together we–you as the client, and me as the consultant–can do better.

What are Specification Documents?

First off, what do I mean when I say “specification document” or “spec doc”? This is the document usually presented at an initial client meeting, which contains a long list of features and descriptions how they should work. Typically, these documents are 30–100 pages long, with several “chapters” (one for each family of functions). Usually, these documents are full of flow charts, architecture diagrams, and maybe even page wireframes.

So, What is the Problem?

What’s so troubling about a spec doc? It seems like it would give us a huge head start in building the system, right?

Here’s the challenge: I’ve never seen a specification document that was research driven. I often ask clients who are brandishing spec docs this question: How many potential or real users did you interview to create those flowcharts and feature lists? After many years in the business, the answer to this question has never been higher than Zero. Ever.

Beyond that, expensive third-party consultants create most spec docs that I see. Nothing wrong with consultants– I’m a consultant! But I wonder if you have ever asked yourself, though, Why isn’t the consultant who made your spec doc the one building your system?

The trouble that I find is that consultants who specialize in making spec docs are rarely capable of, or interested in, building the system. Does it make sense to you that someone who can’t build the system should be in charge of designing the system?

Now, maybe you created the spec doc yourself. It is fine to sketch out your vision, but you hire us so that we can advise you. You hire us because of our experience and process. If you tell us exactly how we must build the system before we consult, you aren’t using that experience and process. It also just isn’t the best use of your time as a busy business owner.

This reminds me of Alfred Korzybski’s expression, “the map is not the territory.” A picture of a system is not the system itself. Even 100-page specs leave out important details. Those important details go unnoticed as people busy themselves checking all the boxes in the spec.

On the flip side, a 100-page specification document includes far more features than you can reasonably build in the MVP version of any software. For startups approaching dev shops with a 100-page spec doc (or even a 30-pager!),  you are asking to spend way more of your money than needed in order to validate your business idea. Start small, cheap and fast.

The Counter-Argument in Favor of Specs

The counter-argument in favor of the up-front spec document is that it creates one source of truth.

Here’s the rub: If I’m serving you and not the spec, that truth instantly becomes fiction. We constantly find better ways of doing things through discovery and expertise. Would you rather we give you the better thing, or the one that matches the spec? If we make the better thing, we have to go back and update the spec doc. Why? Because we’ve had handshake agreements to change written specs before, and they are always forgotten at the end of the project and when things get tough. Now I am serving the spec in a different way– by constantly rewriting it– rather than spending my time making your business better.

How do I know what I’m building, you ask? We have a product brief which describes the goals of your system and business in a handful of sentences. We have hundreds of user stories, written from the perspective of your customers. We have you as the owner of the product and source of tremendous insight about your business. I have two decades of experience writing software, and a dozen years of experience as a consultant. These are all valuable and flexible resources for getting your software built that will outlive and outperform any spec document.

So What Do We Do Instead?

So what should we do instead of a spec document?

We do design sprints – a time when we find out what your actual customers want and need. Then, expert Product Managers, Business Analysts, Designers, and Engineers build a realistic roadmap for your product.

We do agile software development – meaning we work in well-defined, small pieces in constant collaboration with you as the product owner and with all the other stakeholders. We move fast and constantly discover.

We do small, quick experiments to validate your idea. For less than the cost of some spec docs, we can build a focused MVP system that real users can use that will test your business idea and illuminate your true path to success.

These are all more worthy of your time and money than a picture of a system.

Please, help us to build the best thing we can for you and your customers. Say hello to Team Revelry here. What can we build together?