The spec first.

Most disputes between a client and a contractor start with the phrase "that's not what we meant." The client expected a catalog with filters but got five pages of text. The developer built what they understood from a verbal conversation and considers the job done. Neither of them is cheating; the agreements just aren't written down anywhere.

A website technical specification solves this problem. Below is how to put one together, what it must contain, and where clients most often go wrong.

Why a website needs a technical specification

A spec records exactly what will be built, how it will work, and by what criteria the work is considered accepted. It is a shared document for the client, the designer, the developer, and whoever will later promote the site.

What happens without a spec

Without a document, the scope of work grows as the project goes on. Every new idea from the client turns into an argument: is it part of the contract, or is it an add-on for extra money? Deadlines slip, the budget grows, and the final site often doesn't resemble what was imagined at the start.

Who writes the document

Usually the website development spec is prepared by the contractor together with the client: the contractor knows which solutions are technically possible, and the business owner knows what customers need. In website development this is standard practice. If one side writes the whole document, it either lacks business details or becomes a wish list that ignores the budget.

Goals and audience: where to start

Start by answering the question of which business task the site solves. Getting service requests, selling products, taking bookings, supporting existing customers: the structure, functionality, and even the choice of platform depend on the goal.

Website format

A single service with a clear offer is often well served by a landing page. A company with a dozen lines of business needs a full website with a separate page for each service. We covered the difference between formats in our article on whether you need a website or a landing page.

Who will use the site

Describe your visitors in plain words: who they are, what device they visit from, what they want to find out before buying. For example, "the chief engineer of a plant is looking for certificates and delivery times" or "a mother is looking for a kindergarten near home and browsing photos of the groups." A description like this helps the designer and the copywriter more than vague words about a "modern style."

Structure and page content

The site structure is a list of sections and pages with a description of what is on each of them. This is where future promotion is laid down: if a service has no separate page, it will be hard to get it to rank in search.

Section map

Build a page tree: home, catalog or services, individual service pages, prices, case studies, reviews, about the company, contacts. For each section, specify who prepares the copy and photos. Content is the most common source of delays, so it's better to agree on it in advance. We covered which sections visitors usually expect in our article on what a company website should be like.

Prototypes

A website prototype is a page layout without design that shows which blocks are placed and in what order. Approving a prototype is faster and cheaper than redoing a finished mockup.

Which pages to prototype

It's enough to make layouts for the standard pages: the home page, a service page or product card, a catalog section, and contacts. The rest are assembled from the same blocks.

What to check on the layout

See whether the first screen shows the offer, the price or a way to find it out, and a contact button. Check whether the page has reviews, guarantees, and company details: Yandex takes such commercial factors into account in ranking.

Functionality and integrations

The functionality section lists everything the site should be able to do, not just display. Each item is best described in terms of a user action and its result.

A typical set for a company website looks like this:

• request forms that pass data to the CRM and notify a manager;
• a catalog with filters, sorting, and search;
• a cost calculator, if the price depends on parameters;
• online payment and a choice of delivery method for a store;
• a customer account, if customers come back for repeat orders;
• data exchange with 1C on stock levels and prices.

Site management

Specify what you will change yourself: prices, news, promotions, products. The choice of CMS depends on this. For a large catalog with data exchange, 1C-Bitrix is often chosen; WordPress works for a services site; and for a small project Tilda is sometimes enough. The main thing is that an employee can make an edit without going to a developer.

Collecting visitor data

Any form on the site collects personal data, so the spec needs to include consent to processing, a privacy policy, and a notice about the collection of technical visit data. These requirements are easier to account for when designing the forms than to add after launch.

Design: how to describe what you want

Design is easier to describe with examples than with adjectives. Everyone understands words like "stylish," "premium," and "minimalist" in their own way, while three links to sites you like and two to sites you don't answer half the questions.

Brand identity

If the company has a logo, colors, and fonts, attach them to the document. If not, plan their development as a separate stage before the mockups. You can design a site without a brand identity, but you'll have to redo it later.

Responsive layout

Most visitors come from a phone, so the mobile version is described on a par with the main one. Separately specify how tables, menus, and forms look on a small screen.

Technical requirements for search

If you plan to promote the site, the basic requirements for search engines should be written into the spec right away. Reworking a finished site for promotion costs more than accounting for everything at the start.

The minimum list of requirements:

1. clear page addresses (URLs) in Latin characters without unnecessary parameters;
2. management of each page's titles and meta tags from the CMS;
3. robots.txt and sitemap files, canonical setup for duplicates;
4. an SSL certificate and a redirect from the unsecured version;
5. Schema.org markup for the organization, products, and services;
6. IndexNow support, so Yandex learns about new pages faster.

Specify the speed requirements separately. Google's benchmarks: the main content block loads in 2.5 seconds or faster, the response to a user action takes no longer than 200 milliseconds, and elements barely shift during loading. If the site is being migrated from an old version, be sure to add an item about redirecting old URLs to new ones, otherwise you may lose the traffic you've built up.

Timeline, acceptance, and price

The end of the document describes how the work will proceed and by what criteria it is accepted. This protects both sides: the client understands what they are paying for, and the contractor understands when a stage is closed.

Stages and acceptance of work

It's convenient to split the project into stages with a separate deliverable for each:

How the spec affects the cost

A detailed document lets you get an accurate estimate. Without it, any estimate stays approximate: when the price of building a website is quoted as "from" some amount, the final figure almost always turns out higher. When the features are spelled out, the cost of a turnkey website can be compared across contractors item by item, rather than by polished presentations.

Mistakes when writing a spec

The most common mistake is to copy a competitor's site into the technical specification and add "but better." The contractor doesn't know what exactly should be better and makes a copy.

The second is forgetting about content. The site is ready, but there are no texts or photos, and the launch is postponed for months. The third is demanding everything at once: a customer account, a loyalty program, and integration with a dozen services. It's more sensible to launch a working version, watch how visitors behave, and add features as needed. We wrote about which details really affect usability in our article on an unnoticeable but convenient interface.

And the last mistake is not specifying who is responsible for the site after launch. Hosting, the domain, certificate renewal, and backups should be assigned to a specific person or contractor.

If you need a contractor for a ready spec

A good spec turns custom website development into a clear process with a predictable result. Whether it's building a site from scratch, creating an online store website, or developing websites for a network of branches, the stages are the same; only the depth of detail changes. Building websites to a clear brief costs less because less time goes into rework.

The document is useful whichever contractor you choose. Even if you're looking at ready-made templates where you can buy website creation as a package, or want to buy website development from a freelancer, a feature list and acceptance criteria will save money and time.

The epic name. team helps put together the spec and takes on turnkey website development, from prototype to launch and handover of access credentials. We work in Moscow and across Russia. If you've decided to order turnkey website creation or turnkey website development, visit the page describing turnkey website creation and development by our team. How much a turnkey website will cost, the price of each stage, and the timeline: we give all of this after discussing the brief.