"Build us a site like our competitors', only better" - that is how a large share of projects begin, and about as often they end in disputes. The client expected one thing, the developer understood another, and at acceptance it turns out that nobody wrote down what was "obvious". A technical specification is needed precisely so that this conversation never happens: it is a document in which both sides fix in advance what exactly will be built, how it will work and by what signs the work counts as accepted.
In this article we cover why a business needs a specification, what it consists of, how to write one if you are not a technical specialist, and which mistakes are most common.
Why you need a specification and what happens without one
Without a written brief there is essentially nothing to base a project's cost and timeline on: the developer names a figure based on their own guesses about what you meant. You, in turn, judge the result against your own expectations, which are written down nowhere. Most conflicts arise in exactly that gap: "we thought the personal account was included", "and we thought the mobile version was separate work".
A good specification protects both sides. The client gets a clear subject of the contract and acceptance criteria, and the contractor gets protection from endless extra work that was never agreed. It also saves money before development even starts: when functionality is listed item by item, it is immediately clear what the first release really needs and what can wait.
Specification, brief and commercial proposal: what is the difference
These three documents are often confused, although they answer different questions. A brief is a questionnaire in which the client describes the business, audience, goals and wishes; it explains why the site is needed and what you want to achieve. The technical specification answers what exactly will be built and how it must work. A commercial proposal says how much it costs and how long it will take, and is usually based on the brief or the specification.
The working sequence looks like this: first the brief, then, based on it, a preliminary proposal, then a detailed specification, and only after that the final estimate and contract. If you skip the specification and sign a contract straight from the proposal, the price and timeline are effectively an estimate by eye.
What sections a specification consists of
There is no single mandatory template, but the structure of a good website specification is usually similar. It opens with general information: the project name, the goals of the site, the target audience and a description of the business. Then comes a glossary, if the document uses special terms, so that both sides understand them the same way. After that the site structure is described: which sections and pages there will be and how they are connected. The main body is the description of functionality - what the site can do for a visitor and what the admin panel can do for staff.
Next come requirements for design, content and integrations with external systems, as well as non-functional requirements - speed, security, working on different devices. The document ends with the stages and timelines, the acceptance procedure, and the terms of warranty and further support. If a section is missing, it is not necessarily a mistake, but every omission should be discussed deliberately: skipped items are most often the source of disputes.
How to describe functionality
The main trap in this section is wording that is too general. The line "the site must have a product catalogue" equally allows a simple list with pictures and a catalogue with filters, sorting, product comparison and selection by parameters; the difference in cost can be many times over. So describe each function through the user's actions and the result: who does it, what exactly they see and click, and what happens in response.
A convenient technique is to write scenarios. For example: "The buyer picks a product, clicks \"Add to cart\", and sees a pop-up notification and the cart counter. In the cart they can change the quantity, remove an item and enter a promo code. If the product is out of stock, the button is replaced with \"Notify me when available\"." Such a description immediately shows which states must be provided for and leaves far less room for different interpretations.
Describe the admin panel separately: which employees edit which sections, whether different access levels are needed, whether orders and requests can be exported, and how the change history is kept. Clients often forget this part and then discover that the manager finds it awkward to handle requests, because nobody discussed it in advance.
Non-functional requirements: speed, security, load
Non-functional requirements describe not what the site does, but how well it does it. This covers page load speed, working on phones and tablets, supported browsers, and expected load - for example, how many visitors the site must handle at once during a sale. If this is not written down, "fast" may mean completely different things to the client and the developer.
Do not forget security: HTTPS, protection of forms against spam and password guessing, separation of access rights in the admin panel, and backups. For sites that collect users' personal data, the specification should separately state the requirements of the legislation of the Republic of Kazakhstan on personal data: consent to processing, a privacy policy and the place where data is stored. It is also worth fixing basic SEO requirements - heading structure, page URLs, meta tags, sitemap - so that promotion does not have to be "bolted on" after launch.
Ask a question or leave a request
Tell us about your task in your own words. Our business analyst will ask clarifying questions and turn your goals into a structured specification with estimates of timeline and cost.
By submitting the form, you agree to the processing of personal data.
Content, design and integrations
The three topics that most often cause missed deadlines are content, design and integrations, and each needs clear agreements in the specification.
Content
It is important to define who prepares the texts, photos and videos, in what form and by what date. If the developer is waiting for materials from the client while the client assumes the studio writes the texts, the project stalls at the very start. A good practice is to state that content entry runs in parallel and that delays on the client's side shift the project timeline.
Design
Describe whether it will be created from scratch or based on a ready-made template, how many home page variants and how many rounds of revisions are included in the price, and for which devices mock-ups are needed. If the company has a corporate identity or brand book, attach it to the specification.
Integrations
List all external systems the site must work with: CRM, accounting systems such as 1C, payment systems, delivery services, mailing tools, messengers. For each integration state which data is passed and in which direction: requests from a form into the CRM, stock levels from 1C to the site, payment status from the payment system into the order. This is one of the most labour-intensive items, and a hidden integration remembered in the middle of the project usually increases both the budget and the timeline.
Stages, timelines and acceptance of work
A large project makes sense to split into stages - analysis and prototypes, design, layout and development, content entry and testing, launch - and to define for each a result that can be shown and accepted. This lets the client step in on time if something goes wrong, rather than finding out at the very end.
Write the acceptance criteria separately. The most reliable approach is to make them verifiable:
- all pages from the approved structure are created;
- request forms arrive in the CRM and at the manager's email;
- pages open without errors in the two latest versions of the main browsers and on phones;
- the page speed score measured with an agreed tool is not below the agreed value.
A vague wording such as "the site must work well" is not a criterion.
Finally, fix the post-launch arrangements: how long the warranty period lasts during which the contractor fixes found errors for free, how a warranty fix differs from new work, and on what terms further support is provided.
How to write a specification if you are not technical
The good news: a meaningful specification does not require technical terms. It is enough to answer a few questions about your business clearly:
- Why do you need the site - to get leads, sell online, inform customers, reduce the load on managers?
- Who is the main audience and how will people use the site?
- Which three to five actions must a visitor be able to complete?
- Which sites do you think are done well and what exactly do you like about them?
The "day in the life" technique works well: describe step by step how a customer arrives at the site and what happens next - from the first visit to payment or a request - and then how an employee processes that request. From such a description an analyst will pick out the functions and integrations on their own. It is also important to split requirements honestly into mandatory and desirable: when everything is "very much needed", you can neither calculate a budget nor choose what to sacrifice when money or time runs short.
Who should write the specification: the client or the contractor
Ideally it is joint work. The client knows their business, customers and processes, but usually does not know how this is implemented technically; the contractor knows the technology and typical pitfalls, but not the nuances of your business. So the scheme that works best is one where the client describes goals and processes, and the contractor's business analyst turns this into a structured specification, asks clarifying questions and proposes solutions the client may not have thought of.
If the client writes the specification entirely alone, without consulting a specialist, the document often turns out either too general or describing an unrealistic solution. If the contractor writes it entirely without the client, it may contain functions the business does not need and lack those it does. In both cases the final document must be read and agreed by both sides, not simply signed.
What to do when requirements change
Requirements change almost always: new ideas appear during the work, the market shifts, details emerge that were not visible at the start. That is normal; the problem begins when changes are made verbally and "on the fly". A sensible procedure is this: any change is formulated in writing, the contractor assesses its effect on timeline and cost, the client confirms, and only then is it included in the work and the specification updated.
This approach does not slow the project down; on the contrary, it protects it: the client understands what each new idea costs and can decide consciously whether it is worth it, while the contractor does not turn into a free executor of endless wishes. It also helps to agree at the start how such additional work is named and accounted for - for example, as separate tasks with a separate estimate.
Common mistakes
The most common mistake is vagueness: phrases such as "convenient interface", "modern design" and "fast loading" cannot be checked, and therefore cannot be a basis for acceptance. Just as often, whole parts are simply forgotten in the specification: the admin panel, the mobile version, emails and notifications, user roles, error pages. The opposite extreme also happens - a hundred-page document in which the main points get lost and which nobody reads to the end.
Typical mistakes also include a lack of priorities: without a split into "must be in the first release" and "can come later", any shortage of time turns into a conflict. Another problem is ignoring integrations and data migration: moving orders, customers and content from the old site to the new one is almost never "simple", and if it is not described, it surfaces later as unexpected costs. And finally, a specification is often written once and then forgotten: after changes are agreed the document is not updated, and by the end of the project it no longer reflects reality.
Checklist for a finished specification
- The goals of the site and the target audience are described.
- There is a site structure: a list of sections and pages.
- Functionality is described with scenarios, not general phrases.
- The admin panel and staff roles are described.
- All integrations are listed, stating which data is passed and where.
- Requirements for speed, security and mobile operation are stated.
- It is defined who prepares the content and when.
- Design terms are written down: the number of variants and revision rounds.
- Requirements are split into mandatory and desirable.
- Stages, timelines and verifiable acceptance criteria are set.
- The procedure for changing the specification is described.
- The warranty period and support terms are stated.
- The document has been read and agreed by both sides.