The Technical Specification: Structure, a Worked Template and the Usual Mistakes

What a specification is really for

A specification is usually justified bureaucratically, as a way for everyone to understand what is being built. That is true but secondary. The real purpose is commercial: it draws the line between a warranty fix and a new paid task. Anything described in the spec and delivered differently must be corrected by the vendor at no charge. Anything absent from the spec you will pay for separately, and that is fair, because the vendor never priced it.

That gives you a simple quality test: a spec is good not when it is thick but when it can settle an argument. Take any line and ask yourself whether, if the result disappoints you, you could point at that line and say "this says otherwise". If the wording allows two readings it is useless in a dispute, which makes it useless in general. Half of the template specifications circulating on the market consist entirely of lines like that.

The second effect is comparable quotes. When five vendors price the same document the spread drops from fivefold to roughly one and a half, because everyone is pricing the same scope. Without a spec you receive five proposals for five different projects and essentially choose at random. This is one of the rare cases where a week spent on a document measurably saves hundreds of thousands of roubles.

And third, less obviously: a spec protects the vendor exactly as much as the client. Without one, "make it look more modern" becomes an endless revision loop that somebody funds with their own time. A good vendor wants a detailed brief at least as much as you do, and their willingness to invest time in producing one is a useful signal during selection.

The structure: eleven sections and what goes in each

The section order is deliberate: it runs from business to technology, and each section leans on the previous one. Starting with page descriptions before goals and user journeys are defined is the classic mistake that produces a site made of attractive blocks with no logic joining them. If you cannot write the metrics section, you do not yet know why you are building the project, and that needs resolving before design rather than after.

The most underrated section is non-functional requirements. It answers the questions that surface after launch: how fast pages load, how many concurrent users the system holds, which browsers and devices it must support, what happens when an external service fails, how often backups run. None of those appear in a mockup, and every one of them costs money if remembered after the build.

The integrations section is almost always too short. "CRM integration" is not a requirement. A requirement describes which data, in which direction, in what format, at what frequency, and what happens on error. A good check: could a developer write the exchange contract from your text without asking a question? If not, the section is unfinished, and the difference between two readings of that line is easily several weeks of work.

The table below pairs a bad and a good version for each section. The difference between the columns is nearly always the same: the bad wording is missing a number, an actor or a testable condition. That is also the fastest way to edit an existing spec, by walking the lines and adding at least one measurable value or one named owner to each.

A worked example: a corporate site for a manufacturer

Below is a fragment in the format of a real specification for a mid-size corporate site: a manufacturer, 24 pages, a product catalogue without online payment, two forms, integration with an accounting system and a CRM. This is the level of detail at which vendors return comparable quotes and acceptance arguments become rare. The full document for such a project runs 15 to 25 pages; what follows are the key statements from each section.

Note the character of the wording. Nearly every line carries a number, an owner or a testable condition. Where a decision is still open, an explicit marker replaces the vague phrase: "to be confirmed before design, owner: marketing". That marker is more honest than an elegant piece of hedging, because it turns an unknown into a task with an owner and a date instead of hiding it until fixing it becomes expensive.

The out-of-scope section deserves its own place. A list of exclusions prevents more arguments than the list of requirements does, because it removes expectations nobody said out loud. Lines such as "a customer account area is out of scope", "multiple languages are out of scope, the architecture allows adding them later" and "post-launch blog population is out of scope" cost one line each and close entire categories of acceptance conflict.

• Goal: 60 organic enquiries per month six months after launch; secondary goal: cut phone requests for datasheets by 40%.
• Audience: industrial procurement officers (70%), design engineers (20%), dealers (10%); core journey: find an item, download the datasheet, request a price.
• Structure: 24 pages including home, 6 services, a catalogue of 12 product pages, about, production, certificates, contacts, blog and 2 legal pages.
• Homepage: hero with offer and form, 4 quantified benefits, 6 service tiles, 3 cases with outcomes, a production map, an enquiry form.
• Functionality: catalogue with 5 filters, search by name and SKU with suggestions from 3 characters, PDF datasheet downloads, 2 forms with validation and consent capture.
• Integrations: hourly REST/JSON pull of catalogue and stock from the accounting system, 3 retries at 5-minute intervals plus an alert on failure; enquiries pushed to CRM with UTM tags; the client IT department configures the accounting side.
• Non-functional: LCP at or below 2.5s on mobile 4G for the 10 most visited pages, 200 concurrent users without degradation, HTTPS, bot protection on forms, daily backups retained 30 days, personal data hosted in country.
• Browsers and devices: the two latest versions of Chrome, Safari, Firefox, Edge and Yandex Browser; verified on iPhone 12 and newer, Android 11 and newer, screens from 360px.
• Content: the client delivers copy for 24 pages and 40 photographs by the agreed date; a delay shifts the schedule by the same amount, recorded in writing.
• Design: brand colours and typefaces from the 2024 guidelines, three references attached, no stock photographs of people, approved by the marketing director, 2 revision rounds per screen included.
• Out of scope: a customer account area, online payment, multiple languages (architecturally allowed for later), post-launch blog population, a mobile app.
• Acceptance: a 40-item checklist, layout conformance within 2px, verification on 5 devices, 5 working days for the client to accept or issue a reasoned rejection.

Writing acceptance criteria somebody can actually test

A testable criterion always has the same anatomy: a measured quantity, a threshold, the measurement conditions and the tool. "The site must load fast" contains none of the four, so it can be argued about forever: on the vendor office connection and a desktop everything flies, on your phone underground it does not, and both observations are correct. "LCP at or below 2.5 seconds on mobile 4G for the ten most visited pages according to PageSpeed Insights" produces no argument at all.

The second technique is turning qualitative requirements into scenarios. Instead of "a convenient enquiry form", write the sequence: the user fills four fields, an error shows a hint under the specific field, submission shows a confirmation, the enquiry arrives in the CRM with UTM tags within 30 seconds, and the sender receives an email. Every step is verified by one action, and the chain as a whole describes what you actually meant by the word convenient.

The third technique is naming the verification tool inside the criterion itself. Layout conformance is checked by overlay within a pixel tolerance, speed by a named service on named URLs, load by a load test with a stated number of virtual users, accessibility by an automated audit plus a keyboard navigation pass. Once the tool is named in the spec, acceptance stops being a discussion of taste and becomes a two-hour procedure.

Fixed price and agile need different documents

Fixed price demands maximum detail, because a fixed price is only possible against a fixed scope. Here the spec describes every screen, field, integration and acceptance criterion, since anything undescribed becomes a negotiation. Such a document runs 20 to 40 pages for a mid-size site, takes two to four weeks to write and costs money. It is justified when requirements have settled and the budget is approved and cannot grow.

Agile and time and materials work differently: only the nearest slice of work is described in detail, while the far horizon stays at the level of goals and boundaries. The document looks like a product vision plus a prioritised list of user stories with acceptance criteria for the next two or three iterations. This is not a lighter spec, it is a different instrument, optimised for the case where part of the requirements only becomes clear once users have touched a first version.

A detailed spec is sometimes actively harmful. It is wasted when the product is exploratory and half the hypotheses will not survive first contact with users; when the market moves faster than development; when the work is under a month and writing the document costs as much as doing it. In those cases detail becomes an expensive way to freeze assumptions that will turn out wrong, and then to pay again for unfreezing them.

A hybrid is the most common arrangement and works better than either extreme: a detailed fixed-price spec for the first release, then sprint-based development billed by time. The client gets predictability where it matters most, at the start, where money is spent before any value exists, and flexibility where it helps, after launch, once real data arrives.

Seven mistakes that generate change requests

The first and most expensive is a spec without metrics. If the document never states why the project is happening and which numbers define success, every decision along the way is made on taste rather than purpose. Such a project cannot prioritise and cannot decline a feature, because the argument "this does not serve our goal" is unavailable when the goal was never written down.

The second is "obviously". Everything self-evident to the client is self-evident only inside their industry and their company. What happens to an enquiry after submission, who replies to the customer, whether request history is stored, what to do with out-of-stock items: you have a ready answer for each, the developer does not. An unasked question always receives a random answer, and the rework costs more than one sentence in the spec would have.

The third is design by committee. When seven people with different interests approve the spec the document doubles in length and loses decisions: every contested point is replaced with hedged wording acceptable to all. The cure is naming one document owner with final say. The fourth, closely related, is the missing content owner: copy and photography wreck schedules more often than code does, almost always because nobody was personally accountable for them.

The fifth is integrations with no exchange contract. The sixth is the absent revision policy: nothing states how many rounds are included or what happens on the seventh, so every change becomes a negotiation. The seventh is having no out-of-scope section, which is the one that prevents the most acceptance conflict, because it removes expectations nobody stated out loud yet everybody held.

• No metrics: no basis for any priority and no basis for declining any feature.
• "Obviously": an unasked question always gets a random answer.
• Seven approvers and no document owner: hedges instead of decisions.
• No content owner: schedules slip on copy and photos, not on code.
• A one-line integration requirement: the gap between readings costs weeks.
• No revision policy: every round becomes a negotiation.
• No out-of-scope section: expectations surface at acceptance.

Who should write the specification

There are three options, each with its own price and its own conflict of interest. The client writes it: cheapest in cash, but the document almost always comes out in business language with no technical specifics, so quotes still diverge. This works when the company has someone with product or technical background and genuine time available, meaning an actual role with allocated hours rather than a marketer doing it between other things.

The second option is the agency that will build the project writing the spec. Technically this produces the best document of the three, because the people who will execute describe what they genuinely understand. The conflict of interest is obvious and worth naming out loud: a vendor tends to describe the scope it is convenient and profitable for them to deliver. The neutraliser is simple, namely paying for discovery under a separate contract, owning the output, and being free to take it to other vendors for comparison.

The third option is an independent analyst or consultant who takes no part in the build. Maximum objectivity and maximum cost: a separate one to three week engagement. It is justified on projects above a million roubles, where the cost of a requirements error is comparable to the cost of the analysis, and in situations where the company internally disagrees about what should be built at all. IT consulting at Veltos.Tech starts at 50,000 RUB, and pre-project analysis producing a specification is the typical format.

The honest conclusion vendors rarely say aloud: paid pre-project analysis is almost always cheaper than a bad specification. One to three weeks of analyst time costs noticeably less than the 30% to 50% overrun that reliably appears when requirements are discovered during delivery. And it has a side benefit: the output belongs to you and stays useful even if you end up choosing a different vendor to build it.

Frequently asked questions

Related services

• IT consulting and product auditThe most expensive mistakes in software happen before the first line of code: a misread problem, a stack chosen out of a contractor’s habit, and a specification that does not exist. Consulting exists to settle all of that before the development meter starts running: what to build, out of what, at what cost and in which order. The result is a document, not an opinion on a call.
• Website development, end to endWe build sites that still hold up a year later: from a one-page CMS build to a store or a web application on React and Next.js. One team for design, code, integrations and launch.
• Web app and Telegram Mini App developmentFor when a site is no longer enough and you need a product: an account area, a dashboard, an internal tool or a Mini App inside Telegram. We design the architecture, write the backend and frontend, and take it to release.

Read next

• How to Choose a Development Contractor: The Question List and the Red FlagsA practical guide to choosing a development vendor: who needs a freelancer and who needs an integrator, the 25 questions for the first call, how to verify portfolio cases and what belongs in the contract.
• What a Website Actually Costs in 2026: The Estimate, Line by LineA practical breakdown of a web development estimate: what analytics, design, front end, back end and integrations actually cost, which expenses always show up after launch, and where cutting the budget is safe.
• MVP in 2026: Real Timelines, Real Budgets and What to CutMVP no longer means cheap and rough. A weak prototype today produces a false negative and buries a workable idea. Here are four MVP tiers with prices and timelines, a framework for cutting scope, and the parts no budget justifies removing.