“Program specification is the process of taking a requirement and reducing it down to the point where a programmer’s skill can take over. It is an act of communication, explaining and clarifying the world in such a way as to remove major ambiguities” –The Pragmatic Programmer

Update 2022-06-03: I’ve published a refined version of this idea

Specification Docs (Spec docs) connect high-level requirements to implementations. They clarify thoughts and gather information needed to do the work right (and do the right work).

This clarification improves design, communication, and project longevity.

Fundamentals (Rational Model)

Specification is really part of the design process, and the ideal design process is known as the ‘rational model’. Fred Brooks, David Parnas, and others suggest that this model forms a useful basis for reasoning about our design process, though it is not what actual processes look like.

The rational design process specifies that every design has:

Goal(s): The primary objective of the design. Outcomes that must be met for the design to have meaning.

Desiderata / Secondary Goals: Desired outcomes that are not necessarily essential for the design success. These goals are subject to tradeoffs when evaluating design decisions.

Constraints: Criteria that are not necessarily desired outcomes but must be met anyway. For example: budgets, timelines, limited space, performance

Utility Function: The measure of design fit to the goals and constraints. Used for comparing solutions

The designer first identifies these guiding concerns. Then, they enumerate all possibilities for each of the criteria (goals and constraints) and the ways they can be combined. Each of these decisions can be represented as a different design branch. Together all these possible branches form the design tree. Finally, the utility function can be used to pick a “best” design branch from this tree.

These concerns may not be explicitly addressed in a spec doc. However, it provides a useful framework for classifying and prioritizing design activities.

Iteration Cycle

Real designs are rarely so clean as to fit the rational model. It is not practical to enumerate every possible design. Rather, the design space is explored bit at a time.

Design (and thus specification) cycles between synthesizing info and running tests. Each iteration breaks some smaller problem out of the whole. A few likely solutions are identified, the tradeoffs of each are weighed against the design priorities, and the findings are folded back into the whole.

The appropriate test will differ for each problem. It may mean talking to the customer, running a survey, researching a framework, drawing a diagram, or even writing some code.

The specification encodes understanding developed from these tests and decisions. Thus, the spec will often evolve as the system design uncovers new understanding.

Scale

“Specification doc” may sound like pages of dry technical prose, but this isn’t necessarily the case. Spec docs are a tool for formalizing thoughts and can adapt to any scale.

Fixing a bug may require a few minutes to identify expected and current behavior. A simple behavior tweak may only need a sketch. On the other end, critical or large tasks may require extensive specification. In some cases, it is even appropriate for the entire team to contribute to a specification.

The only levels of detail that are certainly wrong are none and all (Code Complete p. 119). To find the balance in between, consider

Task importance
Code lifespan
Team experience
Team familiarity with problem

Less formally, the pragmatic programmer says “Some things are better done than described.” When you reach that point, stop specifying. If you are uncertain, favor the side of detail. Some of the most expensive errors come from a false sense of confidence. Erring on detail will uncover discrepancies whereas vague specs will go unchallenged.

Starter Sections

The content of a specification depends on the problem. However, here are some likely sections to get things started.

Motivation: The high level of what is being done, for whom, why, and why now. This should probably always be considered.
Impact: What existing work will be affected and how much. This is especially important for large changes.
Existing work: What code, resources, or other work has already been done. Key for situations that might introduce duplication or have significant research already.
Likely Changes: What aspects of the current work are most likely to change, what are the reasonable changes, how likely are they, and how impactful would they be to accommodate later. This consideration is especially important for new features and critical workflows.
Research: Any surveys, interviews, feedback, or other info that would impact the decision process. Especially important for large and high-impact tasks.
Major components: Diagrams, interface signatures, or other indications of the implementation structure. Especially important when the code structure will be atypical or unclear.
Failure cases: An enumeration of ways the expected task could fail and the recovery behavior. Especially important for completion-sensitive tasks like payment.

Communication

A spec doc clarifies the problem, which also makes an excellent catalyst for communication.

For the writer, the spec doc forces formalization and record of their thought process. This improves understanding and reduces time to resume a task after a break.

Spec docs also provide context when adding collaborators or when the implementer just has a tough question. Contributors can skip the rediscovery or “it depends” phase and provide targeted feedback.

When appropriate, spec docs also enable a design review before any code is written. This can prevent unnecessary work on hard problems or with inexperienced developers.

Spec docs should be preserved in a shared and searchable medium, even the simple ones. Common preservation methods include wiki’s or drive shares. This allows future contributors to understand motivations behind changes in the system, which enables more consistent work, speeds future development, and prevents accidental backtracking in solution functionality.

TL;DR

Spec docs link the design process from high-level requirements to implementations by adding enough clarity for a programmer to code it.

Specification is an iterative process that can be scaled for the need of each task and project. Specifications facilitate communication between team members and preserve reasoning for future contributors.

Spec Docs

Fundamentals (Rational Model)

Iteration Cycle

Scale

Starter Sections

Communication

TL;DR

Further reading

Fundamentals (Rational Model)#

Iteration Cycle#

Scale#

Starter Sections#

Communication#

TL;DR#

Further reading#

Fundamentals (Rational Model)

Iteration Cycle

Scale

Starter Sections

Communication

TL;DR

Further reading