Jackson has a good definition of a software specification, as being the thin layer at the boundary between the environment and the object being specified (he calls these respectively the application domain and the machine). This means that a specification is read from two sides; it's one description usable from two viewpoints.

In the case of a java class, the class specification is a description of the interface between callers of the class and the implementation of the class. In the case of an application program the functional specification describes the interface between the user and the program.

The proper order of development is: analysis, requirements, specification, design, implementation. Analysis involves figuring out what the application domain is like, mapping the territory. Requirements are a concise description of the subset of the application domain that is relevant to the machine; they state what the machine must accomplish but not how it does it. Specifications are at the boundary between the application domain and the machine, defining how the relevant parts of both sides fit together. Design is the construction of the machine internals, which is further broken down into architecture and design.


The trickiest part of software development is coming up with good requirements. This is mainly due to lack of practice; developers are taught how to produce code and ship products, rather than how to analyze domains and interrogate potential users.

The most common error is to include too much implementation bias in requirements, so that too much of the solution is assumed in the problem statement. Experienced software developers learn to ignore what the customer says s/he wants ("A second stairway to the upper floor"), and to ask questions and delve deeper to find out what the real underlying requirement is ("a way to notify someone across the house that it's dinner time").

When requirements are at the proper level, the designers are left with flexibility in coming up with the best solution. Perhaps an intercom, or a call on the phone extension, or a hammer and a hunk of metal, might be a more appropriate solution than a new stairway; if the requirements are overspecified then the only flexibility available to the designer is in designing a smaller stairway in a less obtrusive location. In other words, too specific a requirement leads to an inflexible and uncreative solution.

Note that the "designers" referred to here first create the specification (which incorporates aspects of the problem solution), then proceed to the full-fledged design of the actual machine. Think of them as specifiers (people who make specifications) as well as people who make designs. Note that specifiers must have a stance in two worlds at once, the user's (application domain) and the solution's (machine).

It's also possible to formulate requirements that are too abstract, too removed from the application domain. For instance, "a way to instantly send a message to someone far away" is so general a requirement that it makes it impossible for the designer to take advantage of details of the environment; overkill solutions like a cellular phone result. Stories of military excess like the $900 titanium screwdriver stem from this sort of poor requirement. The optimization of a solution to details of the application domain is where the elegance can become part of a design . Too general a requirement leads to an inefficient (i.e. costly or inconvenient) solution.

In the amorphous world of software products, an application domain is often defined partly or even mostly by the program itself. The overall appliation domain may be something overgeneral like "make the user more productive". Until one knows what a spreadsheet does and how it changes a user's work habits, one can't list the requirements for a new kind of spreadsheet. In such a case, the requirements necessarily contain aspects that seem implementation dependent, but in actuality the application domain is just being defined by the functionality of the software.

When making truly innovative new products, the fact that one is redefining an application domain makes the separation between requirements, specification, and design blurry. Defining them becomes an iterative process of trying out a design, seeing what that implies about how the user would use it, and then improving the design further. The design in question need not delve into program architecture, but it must concern itself with many aspects of the product's user interface. This creative process of defining the spec (and simultaneously the requirements and UI design, at least to some degree), is an organic process that can't be forced into a linear step-by-step process.

The bottom line is that when requirements, spec, and design are done all once, it may not be because the developer is unorganized, but because there's no other way to create the product.

What Is a Functional Specification?

The specifications for application programs are called func specs. A func spec is the design of the user experience with the program. It is therefore written from the user's point of view, explaining how the different parts of the product work together and interact with the user. Really, a better name for it would be the "User Experience Design". The "func" part of the name is the description of what the program does in response to the user's actions; this is called the program functionality.

Func specs are created at increasing levels of detail, in the same way that a tree grows. First the trunk and a few main branches are created (this is a rough or high-level func spec); then each main branch fills out with subbranches; and so forth until a complex and fully detailed func spec is reached.

The writing style in a func spec should be concise. There's a lot of precise information to convey, so use of organizing structures like tables and outlines is recommended. The spec need not include the rationale behind the various decisions; if that is desired it can be in separate sections within the document or in a sister document. Examples should be similarly concise and to the point. The main thing is to clearly separate in your mind the preliminary thinking-it-through documents from the here-are-the-decisions document; the former are wordier and less decisive than the latter.

The func spec says nothing about the algorithms used, except where they are of concern to the user, such as when the performance or compatibility characteristics of the algorithm affect user work. In such cases the relevant characteristics are part of the spec (must do X in Y seconds), but not the algorithms themselves.

The func spec can be viewed from two directions. From the user's point of view, it describes what the program does in response to user actions, in addition to its synergistic viewpoint about the user's conceptual model of the program. The func spec can also be viewed from the program's point of view, as an indication of what the user might do, and what features are in the program.

Unlike a requirements document, the func spec incorporates some details of the solution to the problem posed by the requirements. To fully specify the user experience, the func spec must include a user-concepts design which naturally blends into the underlying program design. In theory the user conceptual model need have nothing to do with the underlying program design, but in practice programmers know that it's hard to hide a mismatch between the two. Typically the mismatches burst forth as ugly functionaly warts big and small throughout the product.

The func spec and the beginnings of program design therefore happen at the same time. However, any aspects of the design that can be put off should be, namely details that don't affect the user's interaction with the program; they will be addressed at length when the program design is done in a later step.

The product feature list and requirements should be used as checklists at each stage of the func spec development, to verify that the user experience still addresses the fundamental project guidelines. The final most-detailed func spec should additionally be complete, in that every question of user interaction is specified.

Substantive changes:
    April 10, 1996: created.
    April 22, 1996: func spec = user experience design.
Copyright © 1996, Steve Colwell, All Rights Reserved
Home page