Website Technical Specification: What to Include and How to Write It

Why a specification is needed and when you cannot do without it

A specification is needed whenever a site is more complex than a three-page business card: an online store, a multilingual corporate site, a project with integrations. For the client it is insurance against hidden extra charges: everything described in the document is included in the price, and everything not in it is discussed as separate work. For the contractor it is the basis for an accurate estimate of time and cost. Without one, both sides keep different versions of the project in their heads, and the gap is discovered only after the money is spent.

What a specification consists of: document structure

A good specification does not have to be long, but it must cover all key questions. For most sites a document of 5–15 pages with the following sections is enough.

• General information: project name, business description, site goal and expected results, for example "collect 30 leads per month".
• Target audience and scenarios: who will use the site and what a visitor should do on each page.
• Site structure: the list of pages and sections, menu, links between pages.
• Functional requirements: forms, catalog, search, personal account, integrations, languages, user roles.
• Non-functional requirements: loading speed, responsiveness, security, accessibility, supported browsers.
• Design: references, brand book or its absence, number of mockups and revision rounds.
• Technical decisions: CMS or technology stack, hosting, domain, backups.
• Stages, timeline and price: what is delivered at each stage and when.
• Acceptance criteria: the signs by which the work is considered complete.

Example website technical specification structure (table)

Below is a condensed example of how a technical specification is structured: what goes into each section and how to fill it in concretely. Use the table as a template and replace the examples with your project data.

Functional requirements: how to describe them so they can be verified

The weakest link in most specifications is vague wording such as "convenient catalog" or "modern form". A requirement must be such that, after delivery, it can be checked as yes or no. Instead of "fast site" write "the home page loads in no more than 3 seconds on mobile internet according to the PageSpeed test". Instead of "CRM integration" write "form submissions create a deal in the CRM with the fields name, phone and source page". We covered such connections in more detail in the material on integrating a CRM with a website and Telegram. For an online store, describe categories, filters, payment and delivery methods and product import separately.

How to write a specification step by step

Writing a specification is not about producing text but about a sequence of decisions that are better made before development than during it. The fastest way is the following order.

• Formulate the site goal in one or two phrases and choose one main metric.
• Collect requirements from the people who will use the site: sales, marketing, support.
• Draw up the page structure and describe what a visitor should see and do on each page.
• Fix the features and integrations; split them into "must have at launch" and "can wait".
• Agree technical questions with the contractor: CMS, hosting, languages, security; our overview on choosing a CMS can help.
• Describe stages, timeline, payment schedule and acceptance criteria.
• Add a change procedure: who may change requirements, in what format and how it affects timeline and price.

Sample: what a section of a specification looks like in practice

Here is a short example of how to describe a lead form for a business card site. Goal: a customer leaves a request and the manager receives it within a minute. Requirements: the "name" and "phone" fields are mandatory, the phone is checked against a format; after submission the visitor sees a confirmation, and the manager receives an email and a Telegram message; all requests are stored in the admin panel; the form is protected from spam. Acceptance criterion: a test request reaches the manager's email and Telegram within one minute. Every functional block is described in a similar way. If you are planning a simple project, see our article on creating a business card website, which covers a typical structure.

Acceptance criteria and the change procedure

The acceptance section is often skipped, yet it is what closes a project without conflict. Describe what exactly the client checks, within what period they must confirm the result or send comments, and how many revisions are included in the price. Separately, state how new wishes are handled: they are outside the current scope and are estimated as additional work. Also define the warranty period and the terms of further maintenance; more on that in the article on website technical support after launch. The contractual side, covering code rights, deadlines and liability, is analyzed in the material on a website development contract.

Common mistakes when writing a specification

These mistakes occur even in large companies, and each usually costs weeks or extra money later in development.

• Vague wording with no verification criteria: "beautiful", "fast", "convenient".
• No priorities: everything looks equally important, so the budget goes to secondary things.
• Ignoring content: who prepares texts, photos and translations and by when; this problem most often delays a launch.
• Forgotten non-functional requirements: speed, security, mobile version, SEO settings.
• No change procedure: new wishes appear along the way and the parties argue about whether they are included in the price.
• The specification is written by one person: without sales, marketing and support, real scenarios disappear from the document.

Checklist before handing the specification to a contractor

Before sending the document, quickly check it against the list below. If several answers are "no", it is better to spend one more day refining it than a week on approvals later. If you are not sure how to describe certain requirements, most studios, including our website development team, help draft the specification during the project estimate.

• The goal and the main metric of the site are stated in one sentence.
• There is a full list of pages and features with priorities.
• Every requirement can be checked against a concrete criterion.
• Integrations, languages, user roles and content sources are described.
• Stages, timeline, payment schedule and the number of revision rounds are specified.
• Acceptance criteria and a change procedure are included.

Website Technical Specification: What to Include

For international clients, a website technical specification is the document that removes ambiguity between you and a development team in another country. It should be written in plain English, contain verifiable requirements and leave no room for "we assumed that was included". If you work with our team from abroad, prepare at least the points below; we can help complete the rest during the project estimate.

• Project overview: business, goal, target markets and success metric.
• Target audience, languages and key user scenarios.
• Site map: pages, navigation and content types.
• Functional requirements: features, integrations (payment, CRM, shipping) and acceptance criteria for each.
• Non-functional requirements: performance targets, security, accessibility, browser and device support.
• Design: references, brand assets, number of concepts and revision rounds.
• Technology: CMS or stack, hosting, domain, backups, third-party services.
• Content: who provides texts, images and translations and by when.
• Timeline, milestones, payment schedule and change-request procedure.
• Acceptance criteria, warranty period and support terms.