Technical Specification

What a technical specification is

A technical specification — often shortened to "tech spec" — is the detailed engineering description of how a particular system or component will be built. It states what the thing must do, the qualities it must have, the design that satisfies those demands, the interfaces it exposes and consumes, the data it works with, the constraints it lives under, and the conditions that prove it is finished. Where a product requirements document says what the business wants and a system architecture says how the whole platform fits together at a high level, the technical specification sits in between: it turns one slice of that architecture into a buildable, testable plan that an engineer can implement without inventing the missing details.

The audience is the engineers who will write the code, the reviewers who approve the design before any code exists, and the testers who verify it afterwards. A good tech spec removes guesswork. Two engineers reading it should arrive at the same understanding of the behaviour, the same idea of the interfaces, and the same checklist for declaring the work correct. It is written before implementation precisely so that the hard thinking happens on a page that is cheap to change, rather than in code that is expensive to rewrite.

Functional versus non-functional requirements

The heart of any tech spec is its requirements, and they come in two distinct kinds that are easy to confuse but must be kept apart.

Functional requirements describe what the system does — the observable behaviours, the inputs it accepts, the outputs it produces, and the rules it applies. "The service accepts a request to send a notification and delivers it to the recipient's preferred channel" is a functional requirement. They answer the question, "what should happen when...?"

Non-functional requirements describe how well the system does it — the qualities and constraints that apply across the behaviour rather than to any single action. Throughput, latency, availability, security, scalability, and maintainability are all non-functional. "Ninety-five percent of notifications are dispatched within two seconds of being accepted" is a non-functional requirement. They answer the question, "how fast, how reliable, how secure, how much?"

Both matter. A system that does the right things but is too slow, too fragile, or too insecure to use has met its functional requirements and failed anyway. Strong specs number both kinds separately so each can be traced to a test, and they make the non-functional targets measurable rather than aspirational — "fast" is not a requirement, "under 200 milliseconds at the 95th percentile" is.

What a technical specification covers

A complete tech spec moves from intent to verification in a predictable order, each section doing a distinct job:

• Overview and goals. A short statement of what the component is, the problem it solves, and the goals that shape the design — plus explicit non-goals so the boundary is a decision, not an accident.
• Functional requirements. The numbered behaviours the system must exhibit, stated so each can be reviewed and traced to a test.
• Non-functional requirements. The numbered quality targets — performance, reliability, security, scalability — each with a measurable threshold.
• Proposed design and approach. How the component is structured internally and how it satisfies the requirements, described in prose and tables rather than only a diagram.
• Interfaces and APIs. The contracts the component exposes to callers and depends on from others — the operations, their inputs and outputs, and their error behaviour.
• Data. The entities the component owns or touches, their key fields, and how they are stored and validated.
• Dependencies and constraints. The external systems, libraries, and platform limits the design must respect, and the assumptions it rests on.
• Acceptance criteria. The concrete, checkable conditions that must all be true for the work to be accepted — the contract for "done."

Open questions belong in a spec too. An honest list of what is still undecided is far more useful than a false impression of completeness.

Describing the design in words

A tech spec usually wants to show structure — modules, call paths, state transitions — and the temptation is to lean entirely on a diagram. Resist it. A document that is only pictures rots the moment the design shifts, and it excludes anyone reading on a small screen or with a screen reader. Describe the design in prose first: name each part, state the single responsibility it owns, and describe each interaction as a sentence — "the dispatcher reads a job from the queue, looks up the recipient's channel preference, and hands the message to the matching channel adapter." A markdown table is often the clearest way to list components against their responsibilities, and a numbered list is the clearest way to walk a reader through a sequence of steps. If you keep a drawn diagram alongside, treat the words as the source of truth and the picture as a convenience.

Writing testable specifications

The single most valuable property of a tech spec is that every requirement can be verified. A requirement nobody can test is a wish, and wishes cause arguments at sign-off. Three habits make a spec testable.

First, make each requirement specific and observable — name real values, states, and messages rather than "works correctly" or "handles errors gracefully." Second, give non-functional requirements measurable thresholds — a number, a percentile, a unit, and the condition under which it holds, so a tester can pass or fail it without judgement. Third, write acceptance criteria as checkable conditions, ideally in a Given / When / Then shape: given some starting state, when an action occurs, then a specific result is observable. "Given a recipient with email as their preferred channel, when a notification is accepted, then an email is dispatched and the notification is marked as sent" can be tested directly; "notifications are delivered reliably" cannot. Written first, these criteria shape the implementation and double as the test plan.

Common mistakes to avoid

• Blurring functional and non-functional requirements. Mixing "what it does" with "how well it does it" hides gaps in both. Separate and number them so each is reviewable and traceable.
• Unmeasurable non-functional targets. "Fast," "scalable," and "secure" are not requirements until they carry a number and a condition. Replace adjectives with thresholds.
• Only the happy path. Most defects live in timeouts, empty inputs, duplicates, and partial failures. Specify the error behaviour and the boundary cases, not just the success case.
• Diagrams with no prose. Pictures drift out of date and exclude some readers. Describe structure and flows in words and tables; keep any diagram as a secondary aid.
• Vague interfaces. "Call the API to send the notification" loses; the operation, its inputs and outputs, and its error responses, laid out explicitly, win.
• No acceptance criteria. Without an agreed, checkable definition of done, "finished" becomes a matter of opinion and every review reopens the scope.
• Pretending nothing is unknown. A spec with no open questions usually means the unknowns were ignored, not resolved. List them so they get answered before they become rework.
• Writing it once and abandoning it. Specs drift as questions get answered during the build. A spec that is never updated stops matching the code and stops being trusted.