Spec out the competition

Oh, how I wish the question "Have you ever developed software without a specification?" is a good way to start this blog. Alas, much more apt is this question: "When did you last develop software with a specification?".

How is this blatant disregard of functional specification so readily accepted by software developers? Most of them would certainly agree that specifications are very useful, and the righteous would argue that such a thing is absolutely crucial for success. The reason for this disregard seems to be that we are not worthy, our applications are too small, our company is too chaotic and so on. Like the problem of finding water on Mars, the problem of producing a specification is often side-handed as a thing that should definitely be done, especially at NASA.

I find myself ecstatically in agreement with Joel; he wrote a four part article sequence on the topic of functional specification. He inspired me to write up some of my own musings on this matter (unavoidably muddled up with the truths eloquently highlighted by the big man).

What is a functional specification? It is a body of knowledge that describes an application from the perspective of the end user. The conceptual model and the user interface aspects of the system are important aspects of this perspective. If you are technically inclined, keep in mind that the functional specification avoids describing how the application is (or will be) implemented.

It must aim to be complete, unambiguous and accurate. In addition, it should be easy to read. A tall order, I know. But, be not dismayed, a specification written by a mere mortal will prove to be worth much more than the time spent writing it down.

What happens when there is no specification? When there is no functional specification the implementation work takes longer; the application ends up with features that are less in number and less in utility; and resulting code is difficult to maintain. Here are some factors that contribute to this banal outcome:

• The real problem is identified too late. Mostly things look easy on the surface, and it is in the detail the devil lurks. In some case the objective of the entire exercise can be missed. As highlighted by a (not so imaginary) friend: "We excitedly set out to solve the problem and quickly wrote an application. Now we have two problems."
• Nobody knows what is really going on (and everybody hopes the programmer does). This essentially creates communication problems. The sponsor is unsure about what he is getting; the quality assurance team cannot test effectively, and the technical writer wastes his time by creating manuals that describes everything that is already blatantly obvious to anyone that saw the user interface.
• The lack of information translates to lower productivity (and possibly higher irritation level) of the programmer. The constant distraction of people who want to know yesterday's news makes it difficult to focus on the creation of tomorrow's news. As the application grows in stature this overhead becomes more unbearable.

What then should be in the specification? Clearly, the elusive specification should contain information that solves the problems mentioned before. A common misconception is that a specification helps future programmers to understand the system. Although some programmer may be inclined to read the document, mostly they help themselves from the code (design documents has the potential to be absolutely fabulous - but that is a different story).

However, the specification does help the constantly distracted programmer. Instead of a hasty, cryptic comment that most likely does little justice to the application, he can now response with "Would you kindly read the functional specification?" . The specification should rise to this expectation, and be the reference document for the application. So, here are some ides on its content:

• An overview that describes the utility of the application to its users. Here, some scenarios of use can be discussed to help the reader to understand the problem the user(s) expect to solve or the activity the user performs with the application as part of a broader process.
• Details about the user interfaces, the validation rules, process invariants and so on. It cannot have too much detail.
• A list of non-features that explains what the application does not do. These could come from discussion held at (formal and informal) meetings, where someone expected a certain aspect to be addressed by the application, but is does not. Another source might be features planned for the future, and behaviours that are viewed as unexpected by someone.
• A list of open issues are very useful during the initial stages of the development. It reminds the reader of some aspects that are still under discussion.

When is the specification written? Here is the really big surprise. Nobody must wait for the specification. Those days are so over, wake up and smell with noses! Today things are supposed to be much more agile. Likewise, the specification must become agile.

• The basic idea is to start the project with a functional specification that is on a high level.
• Then, as the project continues, update the specification continuously.
• During quality assurance, verify the specification.
• And update the functional specification before extending the application beyond its initial feature set.

Who writes this thing? The problem seems to be that many organisations does not seem to employ the right guy to do this job. However, they did employ you, and my suggestion is that you should do it. It does not matter where you work in the development process - project manager, scrum master, programmer, quality assurance or even chief technology officer. Simply because no-one does it does not mean it should not be done.

Take ownership of the specification and you'll be guaranteed that it will be done. Yes, your time is limited. But, remember only a few minutes per day will be minutes well spent. For your company and for your career. Go for it!