A spec helps you agree on the result before development starts. It fixes exactly what you are buying. It lowers the risk of rework and extra hours.
In this article we cover the basics. Why a spec is needed, how to begin, how to set the project boundaries, how to describe the structure and how to phrase functional requirements so they help estimate the project instead of inflating it.
A technical specification doesn't have to be a hundred pages. But it should close two things: what you build in the first release and how you'll know the site is done.
Why a website needs a spec and what it fixes at the start
A technical specification translates business expectations into clear requirements. You fix the goal of the site, the set of pages, the features, integrations, content and acceptance rules. The contractor fixes the scope and the constraints. As a result you get a document that's easy to estimate against and to verify the result with.
A spec doesn't have to be a hundred pages. But it should close two things. What you build in the first release. And how you'll know the site is done.
What risks appear when requirements aren't fixed
Without a spec you start discussing the details mid-process. That's almost always more expensive. The design changes because there are no references and criteria. The structure drifts because the goal of the site wasn't defined. Features get added because someone remembered them halfway through development.
Another common risk is hidden dependencies. For example, you planned a simple request form, and then it turns out you need lead delivery to CRM, a notification to a messenger and spam protection. If you didn't fix this at the start, the estimate grows and the timeline slips.
How a spec differs from a contract and a commercial proposal
A commercial proposal shows the price and the scope in general terms. It helps you choose an approach. But it rarely lays out the site's behavior step by step.
A contract fixes the legal terms. It covers deadlines, payment, liability and the handover procedure. But a contract shouldn't describe every screen and every form error.
A spec describes the product. It answers what exactly will be on the site and how it works. A contract usually references the spec as an appendix. That's how you link the legal part to a concrete result.
Who is involved in preparing the spec on the business and the contractor side
On the business side you usually need a person who owns the result. Often it's the owner, the director or the head of marketing. It's important for them to formulate the goal, the priorities and the budget and timeline constraints.
You also need someone who knows the processes. For example, a sales manager, a clinic administrator or the head of support. They'll tell you what questions customers ask and where requests get lost.
On the contractor side, the project manager, an analyst and a UX specialist take part in preparing the spec. Sometimes a designer and a developer join if the project is complex. Their job is to clarify the scenarios, resolve contradictions and describe requirements so they can be built and verified.
Where to start preparing the spec before describing pages and features
Don't start with the menu and the blocks. Start with the meaning. A website is a tool. If you don't understand what it's for, you won't be able to cut away the excess.
At the start you need a short set of inputs. The goal, the audience, the decision scenarios, the references. This is the foundation on which the structure, features and design are later built.
The goal of the site and one main target action
Formulate one main goal for the site. Not ten. One. For example, submit a request for a quote, book a consultation, call, place an order.
Next, fix one main target action. This is what you want to get from the user most often. It shapes the structure, the texts and the design. If the main step is a request, you build the path to the form. If the main step is a purchase, you build the path to the cart and checkout.
Test the goal with a simple question. What has to happen for you to say the site works. If there's no answer, the spec will start to sprawl.
Audience and scenarios: how people make decisions
Describe 2 or 3 key audience segments. Not by age. By task and motive. Who these people are and why they need your site.
Next, describe the scenarios. Briefly and step by step. For example, this path.
- A person searches for a service in Almaty
- Opens the site on a smartphone
- Compares prices and timelines
- Looks at examples of work
- Asks a question in a messenger
- Submits a request
Scenarios help you understand which pages are needed, which blocks matter and where to place the calls to action. They also help describe the site's behavior in the functional requirements.
References and counter-examples to remove subjectivity
Collect 3 or 5 references. State exactly what you like about each. Don't just write 'I like the design'. Be specific. For example, a short first screen, a clear form, the service structure, the way cases are presented, the illustration style.
Add 2 or 3 counter-examples. And explain why for these too. For example, lots of text with no meaning, a complicated menu, tiny buttons on mobile, intrusive pop-ups.
References remove arguments at the design stage. They save time. And they reduce the risk of rework.
Project boundaries so the estimate doesn't balloon
Project boundaries are the main tool for controlling the budget. You choose what you do now and what comes later. And you fix it in writing. Without this, any idea turns into a task, and any task turns into a bill.
In the spec it's important to separate the first release from future development. And to spell out how you'll handle changes.
What goes into the first release and what we postpone
Make a list of features and sections. Split it into two groups. The first release and 'later'.
Into the first release put everything that leads directly to the main target action. Move the rest into future development. For example, a blog, a personal account, complex filters, second-tier integrations, multi-warehouse, advanced analytics.
Such a list helps estimate honestly. And it helps avoid arguing mid-project about why something isn't there.
How to describe an MVP without losing the meaning
An MVP is the minimal version that solves the core task. It shouldn't be raw. It should be simple.
Describe the core. Which pages and features are needed for the user to reach the target action. For example, this set.
- Home page
- Services
- Prices or packages
- Cases or portfolio
- Contacts
- Request form
- A basic admin panel for edits
If the site is meant to collect requests, the MVP doesn't require complex animation and dozens of unique pages. It requires a clear offer, an understandable structure and working forms.
Rules for handling changes: versioning and sign-off
There will always be changes. The point isn't to forbid changes but to manage them.
Fix a rule. Every change is logged as a separate edit. You describe what changes and why. The contractor assesses the impact on timeline and cost. You sign off. And only then does the task go into work.
That way you don't pay for chaos. And you don't argue at acceptance about what was in scope.
Site structure and standard pages: what to describe in the spec
The structure is responsible for the user journey. It shows how a person finds the information they need and how they reach a request. In the spec the structure should be clear and verifiable. A sitemap and a set of page templates work best.
The sitemap and navigation logic
Build a sitemap. It's a list of sections and pages in a hierarchy. It helps you spot what's excess and what's missing.
Next, describe the navigation. How a person reaches the key pages. Through the menu, through blocks on the home page, through internal links, through the footer.
If you have many services, fix a rule. How you group the services. How you name the pages. How you build the breadcrumbs. This helps avoid confusion and duplicates.
Page templates and blocks on the page
You don't need to spell out every page as unique. Describe the standard templates.
Usually a business needs only a few types. Home, a service page, an about page, cases or portfolio, contacts, a blog article, a privacy policy.
For each template list the blocks. For example, for a service page.
- A first screen with the offer and a button
- A description of the problem and the solution
- The stages of work
- Examples or results
- Frequently asked questions
- A request form
- Contacts
This approach speeds up design and development. And it makes the estimate more predictable.
Request forms and contact scenarios
Forms often look simple. But they're exactly what breaks conversion if they weren't thought through.
Describe which forms are needed. Where they sit. What fields they have. What happens after submission. What text the user sees. Where the request goes.
Describe the contact scenarios. For example, a call, WhatsApp, Telegram, email. Specify which pages you want to show quick contacts on. And how you'll count these inquiries in analytics.
Functional requirements: how to describe the site's behavior
Functional requirements answer what the site does after the actions of the user and the administrator. Here it's important to write not in general terms but in scenarios. What was clicked. What was seen. What was saved. What was sent.
Even if the functionality is standard, the descriptions are still needed. They help avoid different interpretations even in simple things.
User roles and access, if they're needed
If the site is just a storefront, there may be no roles. But if there's a personal account, gated content or different access levels in the admin panel, the roles need to be described.
List the roles. For example, administrator, content manager, moderator. Specify what each one can do. What they can edit. What they can't see.
Roles affect the cost because they require access logic and testing.
Scenarios and error states: what happens after an action
Describe the action scenarios. For forms, search, filters, booking, payment, if they exist.
For each scenario describe the states.
- Success
- Error
- Empty result
- Re-submission
- Timeout
An example for a form. The user filled in the fields and pressed submit. The site shows a successful-submission message. The site sends a notification to the responsible person. If a field is filled in incorrectly, the site shows a hint. If the server doesn't respond, the site shows a clear error and offers to retry.
Such scenarios save time on testing and fixes.
The admin panel: who manages the content and how
Describe who will update the site. And what exactly they'll change.
List the content entities. Pages, services, news, cases, employees, reviews, vacancies, if they exist.
Specify which fields are needed. Title, text, photo, SEO fields, sort order, publication status.
If you want the site to be manageable without a developer, fix this as a requirement. A convenient admin panel lowers the cost of ownership, because you pay less often for minor edits.
Integrations and external services that are most often forgotten
Integrations almost always surface late. At first it seems the site and a form are enough. Then requirements appear from sales, accounting and marketing. And that immediately affects the estimate.
In the spec it's better to list all external systems. Even if you'll connect some of them after launch. Then the contractor lays down the right architecture and won't rebuild the forms, the admin panel and the notifications.
CRM, telephony, messengers and email
If you manage leads in a CRM, fix this right away. Describe where the request should go. Which fields are passed. How you mark the source of the inquiry.
If you take calls, add telephony as a channel. Describe the scenario. The user tapped the number on mobile. You log the call as an inquiry. The manager sees where the contact came from.
If you communicate over WhatsApp or Telegram, specify what's needed. A button with a quick jump. A chat widget. A request notification to the right chat. These are different tasks. They affect the timeline differently.
For email, fix the minimum. Which addresses notifications go to. Whether a copy to the client is needed. Whether email templates are needed. Whether different forms need different emails.
Payments, delivery, maps and notifications
If the site accepts payments, describe the scenario down to the details. What we sell. How the total is calculated. Whether a cart is needed. Whether payment statuses are needed in the admin panel. What the user sees after a successful payment and after an error.
If you plan delivery, don't just write 'delivery'. Clarify what exactly is needed in the first release. Cost calculation. City selection. Time-slot selection. Status tracking. Connection to an external service. Each option increases the scope.
Maps often seem like a trifle. But they too require requirements. One point on the contacts page or several branches. Whether address search is needed. Whether route-building logic is needed.
Notifications matter too. SMS, email, messengers. Describe which events should trigger them. Request submitted. Booking confirmed. Order paid. The manager hasn't handled a lead within N minutes. If this isn't described, the team will start guessing the notifications during development.
Analytics: the events and goals the site should send
Without analytics you won't understand where the site loses customers. So in the spec fix exactly what you measure.
List the target actions. Form submission. A click on the phone. A click into a messenger. Going to the cart. Payment. Downloading a price list, if there is one.
For each action describe the event. What counts as success. For example, not the click on the submit button, but the appearance of the successful-submission message.
Fix where you look at the data. What access is needed. Who is responsible for the check on launch day. These are simple items, but they often save weeks of arguments after release.
Related service
We'll help shape the spec, design the structure and estimate the site without surprises
We clarify the goal and the target action, describe the first release, forms, integrations and acceptance criteria. The result is a structure, prototypes and a clear estimate that shows exactly what you're paying for.
Design and content: how to describe them without the words 'beautiful' and 'modern'
Design can't be verified with the words 'beautiful' and 'modern'. These words fix nothing. In the spec it's better to describe concrete inputs and rules. Then the contractor delivers the design faster, and you accept it more calmly.
Content also affects the timeline and the budget. If there's no content, the site doesn't look finished. And the project stalls at the final step.
Brand materials, typography and rules for the interface
Collect everything you already have. Logos in the required formats. Brand colors. Fonts. Sample presentations. A tone-of-voice guide, if you have one.
If you don't have a brand book, fix the minimum. The main color. The additional colors. The photo style. The icon style. A principle for buttons and links. A principle for headings and text.
Add the references from the first part of the spec. They replace subjectivity. And they help sign off the design not by taste but by the given benchmarks.
Responsiveness and accessibility requirements
A site is almost always viewed on a phone. So in the spec fix that you accept the project across its responsive versions. List the key pages you'll definitely check on mobile.
Add accessibility requirements at the level of common sense. Readable text. High-contrast buttons. Clear error states on forms. A visible focus on active elements. This affects both UX and trust.
Who prepares the texts, photos and video, and in what format
Decide who owns the content. Who writes the texts. Who selects the photos. Who signs off the legal documents.
Describe the scope. Which pages must be filled in at launch. Which can be left with temporary content. If you want a turnkey launch with content, fix this as a separate task.
Fix the formats. The logo in vector. Photos in good quality. Video with clear links and rights. The more precise the inputs, the less rework at the layout stage.
Non-functional requirements that affect cost and timeline
Non-functional requirements aren't about blocks and buttons. They're about how the site works technically. Speed, security, the SEO foundation. These items are rarely visible in a mockup. But it's exactly them that often raise the estimate when they surface at the end.
Loading speed and performance requirements
Describe the speed expectation as a requirement for the result. Don't just write 'a fast site'. Specify that you'll check the speed after launch and on which pages.
If you're planning a large catalog or a lot of media, say so right away. This affects the architecture, file storage and optimization.
If you plan for load growth, fix that too. Even without exact figures. The contractor should understand that you're not building a site just for a business card, but preparing a platform for growth.
Security, backups and access rights
Fix the basic security. HTTPS on all pages. Access separation in the admin panel. Strong passwords and rules for storing credentials inside the team.
Add a backup requirement. How often backups are made. Who stores them. How recovery happens. This is part of the cost of ownership. And it's better to settle it at the start than after the first problem.
If the site collects personal data through forms, fix that the required pages and consent checkboxes must exist. And that forms shouldn't be submitted without consent, if you decide so.
The SEO foundation: addressing, indexing, redirects, the sitemap
SEO doesn't start with texts. It starts with page addresses, indexing and technical cleanliness.
In the spec describe the URL rules. Clear addresses. A logical structure. A single format for services and articles, if there's a blog.
Describe what should be in place at launch. A robots.txt file. A sitemap.xml file. Correct redirects when things change. A 404 page. These are simple things. But without them the site loses visibility and traffic, and fixes after release cost more.
If you already have an old site, add an item about migrating the pages. Which URLs should be kept. Which should be redirected. This protects you from losing the positions you've already earned and the saved links.
Acceptance and readiness criteria: how to verify the result
Acceptance protects the budget just as much as the project boundaries do. If you haven't described how you check the site, you'll argue on feelings. The spec should give a clear checklist. Then it's easier for both you and the contractor to close the project.
A testing checklist across different devices and browsers
Make a list of what you check at acceptance. The main pages. The service pages. The forms. The contacts. The policies. The error pages.
Describe the devices. At minimum a smartphone and a laptop. If the audience often uses iPhone or Android, just fix that you check both types.
Describe the basic checks. The layout doesn't break. The text is readable. The buttons are clickable. The menu works. Nothing overlaps or disappears.
How to accept forms, integrations and notifications
Make test requests. Verify that the form submits. Verify that the user sees a clear result. Verify that the request arrived in the right place.
If there are integrations, verify them by facts. The data was passed. The fields matched. The source of the inquiry was saved. The notifications arrived where you specified.
Ask the contractor for a list of test scenarios. And add it to the spec as an appendix. This simplifies handover and reduces the risk of missing a critical error.
How to measure quality by metrics and facts, not by feelings
Site quality isn't only the design. It's stable operation and a clear user journey.
Fix the metrics you can verify. The number of goals in analytics. The correctness of form submissions. The absence of broken links on key pages. Correct redirects, if you're migrating old URLs.
Add business criteria. For example, the manager receives requests and sees the contacts they need. The administrator can change content without a developer. The user can book or submit a request from a phone without extra steps.
These criteria help you accept the site calmly. And they help you avoid overpaying for endless taste-based edits after release.
Common spec mistakes that make you overpay
The price grows not out of greed. It grows out of uncertainty. When there are few facts in the document, the contractor budgets time for clarifications and rework. And the business pays for those hours.
Below are the mistakes that most often turn a reasonable estimate into an expensive project.
Vague wording and the absence of scenarios
Phrases like 'a convenient interface', 'a modern design', 'high speed' don't work. They give the developer nothing to stand on. They give you no acceptance criteria.
Replace judgments with behavior and verification. What the user does. What they see. How many steps they go through to the target action. What happens on an error. Which fields are required. Which notifications get sent.
If you haven't described the scenarios, the team starts guessing. Then you start reworking. And every round costs money.
Unaccounted integrations and last-minute content
Integrations often surface at the finish. CRM, messenger notifications, email templates, analytics, spam protection. Every such task drags along edits to forms, the admin panel and the logic.
Content has the same effect. If texts and photos arrive late, the layout stalls. The design has to be adjusted to the real volume. New blocks and new pages appear.
In the spec it's important to fix the list of integrations and the content owner in advance. And it's important to specify what's ready at launch and what will be provided later, with concrete deadlines.
Mixing first-release wishes with future improvements
A common mistake is to put every idea that might one day be useful into the first release. As a result you pay for features that don't affect the site's main goal right now.
Split the requirements into two parts. The first release and future development. For development a list and some principles are enough. What you definitely want later. And what's important to account for in the architecture so you don't rebuild the foundation.
That way you preserve the budget. And you don't hold up the launch over secondary tasks.
How Qazaqsoft helps shape the requirements and estimate the project without surprises
A good spec doesn't start with buttons. It starts with the business task. We help translate the task into clear requirements. And we fix what can be built and verified.
How the analysis and design stage goes before development
We start with analysis and planning. We clarify the goal of the site and the key target action. We resolve questions about structure, content and integrations. We define the first release and what goes into future development.
Next we design the logic. We form the structure and the user scenarios. After that the team can estimate the scope and timeline more precisely. And fix them in the contract.
What you should get at the end: structure, prototype, acceptance criteria
At the end it's important to get a set of documents that's convenient to work with and to verify the result against.
- The site structure — a clear map of pages and the navigation logic
- Prototypes of the key pages — they show the blocks and the order of meaning, not the decor
- Acceptance criteria — a checklist for forms, integrations, notifications, responsiveness and basic SEO preparation
When these things are fixed, the discussion runs on facts. This reduces the risk of rework and disputed interpretations.
When it makes sense to start with an audit of the current site and processes
Sometimes it's easier not to write a spec from scratch. It's easier to start with an audit.
An audit is needed if a site already exists but isn't bringing requests. Or if the business changed its services and processes while the site stayed old. Or if you're planning a redesign but don't understand what exactly breaks the conversion.
In such situations an audit helps gather requirements from real data and problems. And only then move on to design and an estimate.
