jump to navigation

Bad Functional Specifications July 12, 2007

Posted by newyorkscot in Client Engagement Mgt.

How many times do you get a functional requirements document that has been very carefully prepared for you in advance, only to realize within nanoseconds what a the can of worms you have just split open ? And that this is going to be a very painful exercise in figuring out what the original intention of the system was supposed to be ?

In this day and age of software development, you do wonder how come people can write such bad specifications. There are so many ways of articulating functional requirements, many of which are very simple such as use cases or stories.

It seems to me that the overarching problems with specifications (other than them going out of date as soon as they are completed) are communication and context (or lack thereof). Often the folks doing the specifying suffer from at least one of the following; a) they do not know what other people know and hence how much or little background to give, b) they do not know what the consumer of the specification is looking for (are they building an application, validating a methodology, testing use cases, etc ?), c) they do not know where to draw the line in terms of what is current scope, versus future needs.

After having to digest some of these gems recently, I felt the need to get some “observations” off my chest.  If you need to write a functional specification such that your software development team gets off to a very slow and confused start, please ensure that:

  • Irrespective of content quality, it is large enough to hold a barn door open.
  • It makes gross assumptions – especially where core functionality absolutely needs data that  may not exist.
  • It contradicts itself all over the place.
  • It has plenty of ambiguities and maximizes the overloading of the meaning of words. (Note: if you are going to do this make sure to randomize the use of these overloaded words)
  • It combines irrelevant background and theory with low-level implementation details.
  • If it exists, make sure that the document is based on a previous edition of the system you are trying to build, and provides no foresight into future requirements.
  • It specifies in excrutiating detail every single data field you might need, including temporary data fields that were used to badly program the previous edition of the system.
  • It actually include snippets of badly-conceived legacy code to illustrate future business requirements.
  • It includes highly detailed and comprehensive requirements for features that are not in scope.
  • It copies and pastes mathematical theory from well known resources (such as wikipedia, text books), and deliberately change the explanation of what’s going on. For extra points, omit important transitional steps in the theory.
  • It embeds any concept of workflow deep into the document, and that each workflow process is fragmented and scattered throughout like a jigsaw puzzle.
  • And finally, it never once mentions the functionality required by the actual end-user

More sarcastic contributions appreciated…



1. gus - July 13, 2007

* It makes liberal use of buzz-words such as “leverage” and “synergize”
* It refers to other docs which are either hard to come by or non-existent.
* It tells you to ask a specific person for details (said person may or may not even work for the given organization any more).

2. win - July 9, 2008

Funny Read 🙂
Would you mind putting up another post telling people exactly what you want. You told everyone what not to add in the doc but that’s not much help. If you have the time add the things you do want people to add to the doc. In this way you will get exactly what you want.

3. newyorkscot - July 9, 2008

win – it was a bit of a vent, but I will eventually get round to putting a decent post together as you describe.

Specifics will of course vary on the type of system you are building, but there is a lot of standard concepts that can be followed and used across most situations. These include things like use cases/stories and workflow descriptions / diagrams (interation diagrams, aka swim lanes, are also very good to focus business users on their logic) to build up a list of functional requirements that can be organized (or grouped) into either end-user functionality, dependent functionality, or components/services.This would lead to the creation of a prioritized “backlog” of actionable requirements. Initial specifications around performance (throughput, latency), no. users, geographic coverage, etc would also be nice to get a handle on upfront.

I think one of the biggest problems with specifications is the lack of decent organization and clarity of thought. I would prefer to start with people writing down in very simple terms what the end-user (thinks they) wants and when they want it rather than sitting around waiting for them to come up with something in a vacuum. And then work with them to flesh the specs out in a format a dev team can understand and use. I also find that when given the chance, good dev teams have good creativity and can come up with slick / flexible alternates that might be quicker to implement. Using use cases as the organizing principle to build “end to end” code is also key.

All for now ……

4. Giovanni - September 23, 2009

Something worse than receiving a bad functional requirements document is to be required to participate in the FR sessions for long hours seeing people creating these wonderful documents. It’s impossible to feel productive.

5. Tom - October 19, 2012

As a software engineer I had to review a Software Requirement Specification (SRS) from a group of master students. Although most requirements comply with your observations, these ones really messed with my mind.

[r5] System shall use a file format readable by XML.
[r5.1] Server shall use a WebOS in order to peacefully communicate with a open API that is to be specified.

I know this is an old post, but I hope this inspires other people to share their sarcasm.

6. GSA SER proxies - July 31, 2013

Many corporate networks have the tools in place to allow
VPN access. One of the most common uses for proxies on the internet today are
to access social media networks like Facebook and My – Space.
Still, it usually works well for an occasional refresh.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: