Process

How to write a technical specification for a website

A good technical specification makes a project's budget, timeline and outcome predictable. We explain step by step what the document should include and which mistakes to avoid.

Proses: Veb-sayt üçün texniki tapşırıq necə yazılır
Text size 100%

Most misunderstandings in a website project come not from the technical work but from expectations that were never agreed in writing. The client imagines one thing, the contractor understands another, and the gap only surfaces at handover. A technical specification is the main document that reduces this risk. It describes in one place what the parties are building, why and on what terms. Below we explain a practical structure for such a document and what to write in each section.

Why you need a technical specification

A technical specification is more than a formality. It serves several real purposes:

  • A basis for estimates. A contractor can calculate the budget and timeline correctly only from clear requirements.
  • A shared language. The client, designer, developer and partners all refer to the same document.
  • Change management. Every new requirement not in the document is estimated separately, which prevents disputes.
  • Acceptance criteria. Whether the work is finished can be checked against an agreed list rather than a subjective opinion.

The client can write the specification alone, but more often it is a joint effort: the business side explains the goals and the process, and the technical side turns them into precise requirements.

The business side: goal and audience

Project goal and context

The document should start with the business itself, not with technology. In this section, write briefly and specifically:

  • What the company does and what problem the website should solve.
  • The website's main goal: generating enquiries, selling products, providing information, digitising customer service.
  • How you will measure success: which actions (an enquiry, an order, a sign-up) count as a result for you.
  • If there is an existing website, what should be kept, what should change and why.

Audience and use cases

Who will use the website? Prospective customers, existing customers, partners, job seekers, internal staff. For each group, write down why they come to the website and what they need to do there. For example: "A corporate client reviews the services and requests a commercial proposal" or "An existing client signs in to their account and sees the status of their orders".

These use cases later become the basis for defining the page structure and the priority of features.

Also note the audience's language, location and the devices they use. For example, if most visitors open the website on a mobile phone, the design and features should be thought through for the mobile screen first. If there is an international audience, decide in advance which languages are needed and whether the content will be the same in each language.

Structure, pages and features

Site map

List all pages and sections as a hierarchy: home, services, projects, blog, about us, contact and so on. Give each page a short description: what information it will contain and what the user will be able to do there.

Functional requirements

Describe features as behaviour, not in general terms. Instead of "There should be a search", write: "The user can search products by name and category, and filter the results by price". Typical features:

  • Contact and enquiry forms, and where they are sent.
  • User registration, user accounts, roles and permissions.
  • Catalogue, filters, cart, payment, order statuses.
  • Multiple languages: which languages, and which content will be translated.
  • Admin panel: what staff should be able to change themselves.

Priorities

Mark each feature as "must have", "nice to have" or "later phase". This lets you split the project into phases when the budget is limited.

Technical requirements, design and content

Integrations and technical requirements

If the website does not work on its own, it is important to say so up front. Integrations are usually the most time-consuming part of a project.

  • External systems: CRM, payment system, accounting software, delivery service, e-mail sending.
  • Data flow: which data is transferred, in which direction and when.
  • Hosting and domain: whether the existing hosting will be used or a new one chosen; whose name the domain is registered in.
  • Security: HTTPS, backups, protection of personal data.
  • Performance and compatibility: correct display on mobile devices, supported browsers, page loading speed.
  • SEO basics: a sound URL structure, metadata, a sitemap, redirects from the old website.

Design and content

For the design, attach your brand materials (logo, colours, fonts, brand book) and show examples of websites you like and dislike, with a short explanation. A specific comment such as "This website's navigation is clear" is more useful than "this website is beautiful".

Content should be planned separately. Who will prepare the texts, photos and videos, in which languages, and when will they be delivered? In practice, a common reason for project delays is not the technical work but content that is not ready on time.

A good technical specification does not answer every question, but it shows clearly which questions are still open and who will answer them, and when.

Phases, handover and support

The final section of the document covers project management:

  1. Phases: prototype, design, development, content entry, testing, launch.
  2. Approval points: who approves the result of each phase and within what time.
  3. Acceptance criteria: which checks must be passed and when the work counts as accepted.
  4. Deliverables: access to the admin panel, source code, documentation, training for staff.
  5. Ongoing support: the warranty period, maintenance, updates and how new requirements will be estimated.

The document's format and typical mistakes

Length and format

The length of a technical specification should match the complexity of the project. For a corporate website of a few pages, a precise document of one or two pages may be enough. For a platform with client accounts, integrations and roles, a more detailed description is needed, sometimes with a separate user story for each feature.

Clarity matters more than format. A few practical tips:

  • Use short sentences and numbered lists so each requirement can be referenced on its own.
  • Define terms once and use them in the same sense throughout the document.
  • Where possible, add a diagram, prototype or screen sketch: a simple drawing is understood faster than a long explanation.
  • Record the document's version and the date of the last change.

Typical mistakes

  • Statements that are too general. "A modern, convenient, fast website" is a wish, not a requirement. Turn it into measurable criteria.
  • Describing a solution instead of the problem. Instead of "There should be a pop-up window", first explain what you want to achieve; there may be a better solution.
  • Leaving integrations for later. An integration that surfaces in the middle of the project affects both the architecture and the timeline.
  • Forgetting the content. A website handed over as an empty template does not work.
  • Writing the document once and forgetting it. Agreed changes should be added to the document so it stays up to date.

Conclusion

A technical specification is the project's map: when the goal, users, features, integrations, content and handover terms are in one document, the budget and timeline become predictable and changes stay under control. Do not try to write the perfect document, but keep it precise, specific and up to date. If you do not have a technical specification yet or would like to refine it together, discuss your project with TRUE.

Filed under

Next step

Tell us what you needLet's build it right

Tell us briefly what you want to build. Together we will clarify the need and choose the right technology, expertise and execution model.

Start a project+994 55 754 09 54
  1. You write You describe the goal, the current situation and the result you expect in a few sentences.
  2. We talk In a short meeting we go through the requirements, options and alternatives together.
  3. We present a plan Scope, phases, budget and execution model are agreed in writing.

    Write to us on WhatsApp (opens in a new tab)