Before requirements can be incorporated into computer programs they have to be converted into a format that makes sense for computers... but not down to the level that it works only with one specific configuration. Functional specifications are detailed instructions of WHAT has to be incorporated in a given computer program, while stopping short of HOW the code has to be written. If, for any reason, the actual computer is replaced, then the functional specifications should still be valid for another computer system, or you may want to use the specifications to purchase an application. Functional specifications can be used to write new code, to modify existing code, or to purchase the most closely applicable COTS (Commercial Off The Shelf) software. An important aspect of functional specifications is that it provides a reference that can be used to test the software that is written to (or purchased to) specification. In short, the functional specifications determine the quality that goes into a software development or acquisition effort.

What does this all mean?

The short answer is that all specifications must be measurable and verifiable so that test scripts can be devised to validate that these specifications are correctly implemented. Clearly, if you cannot confirm that some functionality is implemented the way you wanted it done, it becomes more a wish than a requirement. There are ways to verify that all requirements are incorporated in the code by doing walkthrough sessions, but in practice it is difficult to confirm that a requirement is implemented unless you can test that the code functions properly. It is impossible to determine if a COTS product meets your requirements other than through testing. If you make a purchase conditional upon the product meeting your requirements then you have to make sure that these requirements are expressed in unambiguous terms with specific verification rules spelled out. If you have only vague requirements it is not unlikely that your contention that a COTS or purchased custom product is inadequate may be disputed. With tight requirements no vendor would venture to propose a product that does not measure up, because failing a "Proof Of Concept" is a major embarrasment.

Why is it so difficult to write specifications?

For many people the thought process required for writing specifications is the same as for writing code, so why waste time instead of going straight to code? Well, what about the other 98.5% of all people that are not equally inclined to think the same way? Usually the requirements are the first step to an expensive purchase or custom development effort, so you need to find a way to communicate both upwards to non-technical types as well as downwards to the technical staff that will be responsible for the purchase or the development effort. Technical people like to communicate in abbreviations and jargon that mean little to the average end-user. Turning off that normal mode of thinking in order to clearly spell out what the new system is meant to do for the end-user is not a trivial effort. This skill is often referred to as "Technical Writing" that is often performed by specialists, so it is no wonder that the average Systems Analyst feels challenged by this writing assignment. Furthermore, exposing a draft document to a wider audience tends to unleash a lot of negative feedback that questions how well you understand the issues from the client perspective when you simply try to capture your understanding as best possible. Few people are naturally inclined to go out on a limb in order to generate such feedback even if it is for a good cause. Sometimes it is easier for an outsider who can play "dumb" in order to learn what is required.

What is the value of specifications?

The specification stage of a project is where you have the most information while the least number of people are committed to doing work on the project. If there is any confusion, any rethinking, any second thoughts at all, this is the stage where the cost impact is minimal. Assuming of course that the end-users can read the functional specifications, they must think hard about what is being requested, and how the functionality will support the overall business and strategic objectives. Changes made at this stage in the development, before coding has begun, are relatively easy and cheap, and there is little chance that errors will creep into the code as a result of functional requirements changes. In general, these specifications are purely focused on business functions, so that after the functional specifications have been validated by the end-users the non-functional specifications will be added in order to come up with the actual systems design. With the exception of desired performance characteristics and some direction on specific technical requirements the specifications allow the end-users to confirm what they ask for. This leads to a much more appropriate solution to support the end-users.

How much detail is required?

The general approach used by PM4HIRE.COM is to generate sufficient detail to make sure that readers of all levels of technical prowess can consider, and comment on, the specifications. In principle you want to get the most feedback in the shortest amount of time, to help you get the project on track with complete buy-in if possible. There will always be people who are negative in their thinking, but the majority of people will look at specifications to determine what is in it for them. They want to confirm that their job is made easier (but that it is not eliminated) and that they continue to contribute to the bottom line using computer-assisted processes. They do not just want to be told that the functions they perform are valuable to the company: they want to be able to see it for themselves.

PM4HIRE.COM uses a number of quality checks to make sure that the level of detail for the functional specifications is just right:

To be able to verify that requirements are properly implemented it is essential that you have some way of testing and measuring these requirements. For example, it makes no sense to claim that response times must be adequate, because the perception of what is adequate varies from person to person. You would have to state a 5 seconds or 10 seconds limit, or so, that explicitly states what the expectations are and that can therefore be validated as part of the testing process. You need to specify what conditions are handled by the software, how it must respond to different conditions, inputs, and attributes in order to yield specific results. A random number generator may seem simple enough to implement, but specifying that the results must be uniformly random is quite another thing altogether (not only for coding, but also to test and validate that requirement). Nothing in the specifications should be left to the imagination of the developers, although that does not mean developers cannot identify improvements that should first be validated through the implementation change management processes (and then incorporated in the specifications and in the test scripts that are being developed).

To make sure that the functional requirements are fundamentally sound you must be able to trace them back to the user requirements and business requirements that are satisfied by having that functionality. It is not unusual for people to keep adding contributions to the detailed functional requirements, but you have to keep focused on what the business wants and what the designated users want. That does not mean you cannot identify valid new requirements that are not directly related to the designated users or even to the perceived business needs: many needs can be uncovered indirectly, but if that is the case the applicable user needs or business needs should be added to the documentation. In the end the intent is to have a single inventory of requirements that covers all aspects of what needs to be automated in order to satisfy the established business needs. If you do not assure that traceability the consequence may be a system that seems to be a hodspodge of functions that are confusing to the typical user who then has to figure out what business needs can be satisfied in some way. Or, you may end up with narrowly focused systems that individually only cover a small portion of what the users need in order to meet the business objectives. Either way the result is completely unsatisfactory.

To help the developers implement the exact functionality you want it is important to make them specific and detailed enough as to leave nothing to the imagination. To be sure, functional specifications are often difficult to read, just as you are unlikely to curl up in front of the fireplace with a glass of wine to read a cookbook cover to cover (unless you are a cullinary connoisseur). Each recipe defines a unique combination of ingredients just like each functional specification defines a unique combination of inputs in order to produce a desired result. Just like a cookbook recipe the specifications must define the exact ingredients, the amount, the quality, the order in which the ingredients are used, the process involved, and the presentation of the results. Once you start to leave things to the imagination of the individual cook the end result can turn out quite different, just as individual programmers may have their own idea of what is meant by a vague specification. That does not mean all variability is automatically eliminated: good specifications produce functionally equivalent results in different implementation environments (MS-Windows vs. Unix based, for example) even if the presentation may vary in some ways. With good specifications a system can survive technological change by allowing the product to be largely recreated in a new environment with only the minimally necessary changes for specific adaptations.

To validate the implemented functionality you need to independently derive test scripts from the same set of requirements that are used to develop the software. This is an important concept, emphasized in our Quality Assurance segment (click on the button to read more). Independent development teams would have to make the same mistakes (or complementary mistakes) for an erroneous end result to slip through the testing stage. In all probability that is not going to happen, so if a developer makes a mistake in implementing requirements it will be identified as a coding bug, whereas if a tester misinterprets the requirements it will be classified as a script error (which is just as common as a coding bug). The proper classification of the problem will depend on a joint review between the tester, the developer, the analyst, and user representatives, so even if the problem is more fundamental it can be evaluated and resolved. In the absence of clear functional requirements the parties use a best-guess approach to determining how to implement the code, and it becomes difficult to analyze the root cause of any problems that may be identified. Often perceived problems are debated and ultimately turned into "undocumented product features" if nobody quite knows how to deal with them.

To keep the integrity of the software intact over time it is important to have change management control processes in place that validate any request against the approved product requirements. Without controls it is not impossible for the true purpose of the software to erode and for the software to take on new functions that it was never designed for. Sometimes this is a positive development, to keep the software current with demands in the market place, but at other times this leads to the use of an inadequate foundation just to create the false impression that this is a natural evolution when it is not. It is critical for Application Support staff to vet all change requests against the requirements to see whether it is simply an improvement (in which case the code and the documentation can be updated) or a request for net new functionality. In a controlled environment that new functionality should be implemented as a new release provided that it is compatible with the existing code.

We are veterans of this product life cycle concept. We have seen what can happen if you do not touch base with the product stakeholders before you take the functionality in a new direction. We know how important it is to maintain the supporting documentation and to keep the right focus. We know that this is not about stopping change: it is about making sure that you carefully consider whether the tie-in with the existing software makes sense or whether this is a good opportunity to start a new product.