The case against functional specs

By Diego | Software Practices

Feb 02
Stack of Documents

Is there any single way in which you can develop a piece of software that doesn’t do what users want? Yes, write a functional specification document!

Before saying anything else, I want to clarify that I’m talking about typical software projects… web, desktop or mobile apps; not about space shuttle operating systems, or real time controllers for robots that do brain surgery!

I can almost hear all of those functional spec lovers yelling all kind of things at me. – “Are you crazy? Functional specs are supposed to help us in delivering good software, products that do what the users want.” Well… usually we achieve exactly the opposite by creating this documents.

This is one of those areas where reality shows us again and again, how wrong we are.

Please, try to remember any software that you have developed, that once it was finished, still kept quite close to the initial functional spec… I couldn’t. And I know a lot of good software developers with this same dilema. The reason is simple, functional specs are theory, not reality. Of course, we could try to maintain them close to reality and in tune with all the changes and evolutions as we develop the software, forcing us to strictly change first the specs before doing anything else. But then… why bother? Isn’t it supposed to help us? If we have to change it day in and day out, every time we want to make changes, does it worth it? Does it slow us down?

In my own experience with all the corporate clients that I worked for, they always had required some kind of detailed functional spec before starting to build the software. The best scenario was to have a software very different to the initial spec, but fortunately aligned to the client needs. Sometimes these specs where updated, sometimes not. But we always had a lot of overhead with back and forth discussions with clients about what was a “requirement change” and what was a “misinterpreted requirement”, and then rewriting the specs or writing new ones.

And the worst case scenario? Well… if those were some of the best cases, I guess is not necessary to explain what happened when we weren’t so fortunate.

Over the years I came to discover some truths about software development and functional specs, the hard way… hitting my face over the wall. Most of these issues were addressed by other people, and I only wish now that I could had the chance to understand them better back then:

  • People don’t understand specs the same way. Every time you write a spec, you’ll have people thinking different things about the same issue. I saw this happening a lot of times. Even with a paragraph of 1 sentence. There’s always information that’s implicit and existing only in the brain of one person. And of course that information is obvious for this person, but not for all the others.
  • There’s not enough information to make the real decisions at the time you are writing a spec. Usually the information needed arises once you start the development process. So here we are playing with guesses and assumptions, not making any progress at all, and usually discussing things that will not apply later on.
  • At spec time, there is always the tendency to add a lot more functionality that what is really needed, and what it could be built with the available time, budget and resources. People (and usually programmers too! -yes they are different kind of animal-) like to add a lot of functionality to software, because… – “it’s only a button here and there, how much could that cost?”, or… “yes, we need categories and subcategories for this, and would be nice if they could be user defined. This is just two simple drop down lists, very easy right?”. Until you start thinking about all the support code, CRUDs for those “simple” drop downs, tests for the new modules, new deployment code, migrations for the old data to upgrade to the new software version, etc. What seems simple and tiny, almost always grows bigger when you start building it. And of course, the budget is already written in stone!
  • It’s very easy to fall into “Holy Bible syndrome”. Specs are usually used as signed contracts. And once you are there, it’s really difficult to build a useful software. Reality is always changing, signed contracts are just the opposite, always fighting against change (and both sides of the contract, client and provider, in alternating times, assume the “not change allowed” role). I’m not advocating here against software development contracts or trying to evade responsibility and accountability for what developers produce. But transforming a software spec in a kind of Holy Bible it’s not going to solve the real situation that presents every day in these industry: perpetual change. When we use the specs as a signed contract, we loose a lot of time and effort dealing with which changes are allowed or not, with interpretation details of what was asked to do, what was “in there” and what wasn’t. This is dead time. Assume reality, and please work as a team with the same objective: build a useful software.

“So great genius… if we create no spec, how do we start? Do you suggest start coding right from the beginning?”

No, not at all. But I’m for things that really help you build your software, and don’t get in your way. What I really found that works is to start with a really small description of the product or software that you want to build and some UI draft sketches. This will really help you visualize the software you want to build, and to communicate the ideas easy and with low overhead between team members and with your client. The natural evolution of these steps is to start building the real UI, with no functionality.

“Hey! Wait a minute… isn’t that a kind of spec?”. Yes it is, but a different breed. One which is simple and agile enough to help you and your client to agree, and to move on to the real work… getting the product done! I’ll be writing about this process on some future post.

From my own experience, I got the bests results when I kept focused on less documents, more agility, and using the right tool for the job.


About the Author

I’m a software engineer and work as an independent software developer and consultant. Software development is my passion. I usually find some time to write in between my work and my other interests, sports and PC gaming!

(3) comments

Add Your Reply