Technical Spec

Before a team starts writing code, someone often writes down exactly what is supposed to be built. This document is called a Technical Spec, or technical specification. It doesn’t contain the finished program code, but the plan behind it. It describes, for example, what parts the system should consist of and how those parts communicate with each other. The spec also records why one approach was chosen over others. You can compare it to an architect’s blueprint: it shows where the walls and pipes will go, long before anyone lays a single brick.

Why teams write before writing the first line of code

Fixing a mistake in a plan costs almost nothing. You just change a few sentences in the document. Fixing a mistake in finished software, on the other hand, costs weeks. Anyone who takes the spec seriously shifts the thinking to the cheapest point in the project.

A second reason is alignment. Large software is rarely built by individuals, but by groups of ten or a hundred people. Without a shared document, everyone builds what they imagined. In the end, the pieces don’t fit together. The spec is the point where everyone arrives at the same mental model.

It’s important to distinguish this from the Product Requirements Document, or PRD for short. The PRD describes what a product should be able to do for its users. The Technical Spec describes how that is solved technically. So one answers the What, the other the How. In practice, the spec is usually written as a response to a previously written PRD.

What such a document contains

Almost every spec starts with the problem. A sentence or paragraph explains what doesn’t work or is missing today. This is followed by the goals and, explicitly, the non-goals as well. These non-goals are more important than they sound: they record what the project deliberately will not solve, and thereby prevent endless discussions.

The main section describes the planned solution. This includes the individual building blocks of the system, the structure of the stored data, and the interfaces. An interface is the agreed-upon way in which two parts of a program exchange data. Often it also states how the system reacts when something goes wrong. A simple diagram frequently supplements the description.

A good section is called Alternatives. It lists the approaches that were examined and rejected, along with the reasoning. That may sound like unnecessary effort, but it saves a lot of time later. If someone asks a year later why the system was built this way, the answer is right there in black and white in the document. Finally, the spec usually goes through a review, meaning it’s checked by experienced colleagues who leave comments.

From railway station clocks to AI projects

The term doesn’t come from software but from engineering. Before a bridge or a clock is built, there is a specification with dimensions, materials, and tolerances. Software adopted this principle. At large companies like Google or Amazon, writing a spec is a normal part of a developer’s job.

In the news, the term often comes up in connection with standards. When a standards body defines a new version of WLAN or USB, it publishes a spec. Manufacturers worldwide then build devices according to this document so that everything is compatible. AI providers also publish specifications for their interfaces, so other companies can integrate their models into their own products.

A common misconception is that a spec is set in stone. In practice, it’s a living document. As soon as it becomes clear during development that part of the plan doesn’t work, the spec is adjusted. So it doesn’t replace experimentation, but rather gives it direction. Interestingly, AI assistants are increasingly using this kind of text themselves: give a model a clean spec, and you get back noticeably more usable code than with a vague instruction.