How to write a website specification: a working template and checklist

A good specification doesn't describe every pixel — that's impossible and unnecessary. Its job is to fix the business goals, the boundaries of the project and clear acceptance criteria, so that two months into development it doesn't turn out the client and the developer were picturing different websites.

Below is a structure you can use to write a workable spec even without a development background.

1. Project context

Before talking about page structure, write down:

• What the business does and what the site is supposed to achieve — enquiries, sales, reputation, customer support.

• Who the target audience is and what languages they speak.

• Geography: one city, the whole country, several countries.

• How success will be measured — number of enquiries, time on site, conversion from a particular channel.

• Constraints: deadlines, budget, an existing brand book, current infrastructure (hosting, CRM, email).

2. Sitemap and URL structure

A list of every page type: services, case studies, blog, forms, product cards. If the site replaces an old one, you need a mapping table of old URLs to new ones, so search positions aren't lost and external links don't break. Note separately which pages should not be indexed.

3. User journeys

For each important action on the site it helps to write out: where the user starts, where they land, what options they have, and what happens on success and on error. For example: someone finds the site searching for "Telegram bot development" → lands on the service page → fills in the form → sees a confirmation → the manager receives the enquiry in the CRM.

4. Content and who's responsible

Who writes the copy, who translates it, who approves the final version. What materials the client provides — logo, photography, documents. What format content is prepared in for migration from an old site, if there is one.

5. Integrations

For each integration (CRM, payment provider, Telegram bot, analytics) state: who owns the access, where the documentation is, what data is passed and in which direction, how errors are handled, and whether there's a test environment for checking before launch.

6. SEO, speed and accessibility

Unique titles and descriptions for every page, target load-speed figures (Core Web Vitals), and baseline accessibility requirements — keyboard navigation, text contrast, image alt text, structured data.

7. Acceptance criteria

The most underrated section. "The site should be fast" isn't a criterion, it's a wish. "The homepage loads in under 3 seconds on 4G" can be checked, accepted or rejected. The more specifically requirements are worded, the fewer grounds for argument at handover. Write down separately the process for changing the spec after work starts — that's normal practice as long as it's agreed in advance.

A starter template

• The site's goal and how we measure the result.

• Audience and languages.

• List of pages and section structure.

• Key user journeys.

• Integrations and who is responsible for them.

• SEO and speed requirements.

• Acceptance criteria for each point.

At Code Nova Evolution we usually help put a spec like this together during the analysis stage before a project starts — it speeds up development and removes most of the misunderstandings at the outset.