Bad Functional Specifications

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...