an Essential Technical Writing Guide

Practical Project Specification

Specification is a tool for thinking and communicating. It helps clarify requirements and organize work in a format that both stakeholders and implementers can reference and update as the project progresses.

A project spec outlines what is to be done, who it’s to be done for, and (briefly) why. It’s a multipurpose document that throughout its life will act as motivator, implementation guide, acceptance criteria, and documentation.

A spec is not a timeline. It does not detail when the work will be done or who will be doing it, and it may only lightly touch on how.

Nor is it a static document, unless its author expects to forego any learning or opportunities arising during implementation. But at all times its content should be as complete, clear, and thorough as possible in describing the current goals of the project.

Why project specifications are always worth writing

There’s usually a gap between the people implementing a project and the customers it will ultimately serve. If there isn’t, and the customer and implementer are one and the same, a formal specification isn’t needed. As soon as multiple people and interests are involved, however, a spec provides a common touchstone for their work.

For customers, specification illustrates what they will be getting. By using clear, accessible language, they can “preview” the project and negotiate over its outcomes without deep knowledge of the implementation details.

For implementers, specification provides a loose contract and outline of their work. By clarifying requirements early, they can minimize rework and increase the odds of delivering the project on time.

When teams get involved, specification enables collaboration through shared expectations and goals. And while ad-hoc conversations may yield similar short-term results, a spec’s durability will hold up better over the long term, or as project collaborators come and go.

Anatomy of a project specification

Project specifications may vary dramatically in scope and detail. In large, high-risk projects, clear thinking up front can save considerable rework down the line. In smaller projects, a brief plot summary may be plenty. At any size, though, the specification will have three sections:

  1. Motivation, a brief explanation of what the specification is meant to achieve
  2. Requirements, describing what the finished project will look like
  3. References, expanding on details omitted from the rest of the doc

Motivation

Every specification should begin with a brief (2-4 sentences) preamble describing the project’s goals. It should concisely answer:

  1. Who is the project’s customer?
  2. What problem are they facing (i.e., why should they care)?
  3. How does the project address that problem?

This section’s goal isn’t to persuade the reader. That’s for a separate document, the project proposal. At this stage the project’s motivation comes fait accompli, but still provides useful orientation to the reader.

Requirements

This is the heart of the document. The requirements should clearly illustrate what is expected of the finished project. The format may vary, but its language and norms should be familiar to the spec’s likely audience.

  • User stories are fine for this.
  • Acceptance tests are fine for this (if they’re accessible to likely readers)

These requirements should capture both function and behavior, but should minimize the time spent on implementation details. Overspecified projects with little freedom for learning and adaptation during the execution phase will yield worse outcomes than those that focus first on the.

References

The final section of a specification references other documents (a project proposal; implementation plan; related specifications) that are relevant but not crucial to the project at hand. Even if most readers won’t touch these, links to past projects and related thinking will make it easier for everyone to catch up to speed.

Share early, share often

The first draft of a spec will be incomplete, incorrect, and crying out for revision. That’s OK. It’s the starting point of a conversation, not an answer for the ages, and should be written with that spirit in mind. Bringing other stakeholders in to the conversation will help turn up oversights and keep the spec converging towards implementation, and it’s crucial to do it as early as possible.

Updating the specification

The most helpful project specifications don’t sit idle during implementation. When possible, specification should act as both a reference and a record of the project’s evolution. If new insights turns up during implementation, they’re incorporated into the spec.

It may not be possible to update requirements as the project proceeds (when a project is bound to an external contract, for instance), but rigid specifications is a risk to be minimized.

Depending on the cultural norms of the organization, there may not be a formal approval process before new projects begin. If there is, it’s good to reach agreement up front about how the specification may or may not change alongside the project.