How to write a technical specification for development

A good technical specification saves money, not pages: it lets a contractor quote a price that won't drift a month later, and it lets you accept the work against clear criteria. A bad spec is either three lines of “we need a website like our competitors'” or 80 pages of requirements nobody read to the end.

Below is a practical guide to writing a technical specification for a bot, website, app or platform, even if you're not a technical person. We'll go through the structure, show an excerpt in the format of a real spec, list the mistakes that most often lead to rework, and explain how to get a preliminary estimate without lengthy back-and-forth.

Why you need a spec and how it differs from a brief

A brief answers “what's the business and what's the task”. A spec answers “what exactly should we end up with, and how will we know it's done”. A brief takes half an hour to fill in; a spec takes anywhere from a few days to a couple of weeks, depending on the size of the product.

A technical specification does three practical jobs:

• Estimation. Without a list of roles, user flows and integrations, any price is guesswork. When quotes for the same “website” vary 3–5x between contractors, it's usually because each one pictured a different website.
• Agreement. The spec fixes the scope of work. Anything not in it is a scope change to be discussed separately, not “well, that's obvious”.
• Acceptance. Every requirement must be testable: “the request form sends data to the CRM within 5 seconds” can be checked; “a user-friendly form” can't.

For small jobs, like a simple bot or a landing page, a short 2–4 page spec is enough. For a platform or a mobile app, the document grows to 15–40 pages and is usually refined together with the contractor at the prototype stage.

Development spec template: 9 essential sections

This development spec template works for any digital product: a Telegram bot, website, Mini App, mobile app or marketplace. Sections can be shortened but not dropped: an empty section is better than a forgotten one.

If the product is complex, add a glossary (what you mean by “order”, “deal”, “customer”) and appendices: sample documents, exports from your current systems, competitor screenshots marked “like” and “don't like”.

How to write a development spec: user flows, not a feature list

The main mistake is describing the product as a set of screens and buttons. What developers really need to understand is who does what, why, and in what order. So if you're figuring out how to write a development spec that everyone reads the same way, start with user flows.

The user story formula

Use a simple template: “As a [role], I want to [action] so that [outcome]”. For example: “As a manager, I want to get a Telegram notification about a new request so that I can contact the customer within 15 minutes”.

Acceptance criteria for every story

Add 2–5 testable conditions to each story. For the example above:

• the notification arrives no later than 10 seconds after the form is submitted;
• the notification includes the name, phone number, selected service and request source (UTM tag);
• the “Take it” button changes the request status and hides it from other managers;
• if the manager doesn't respond within 15 minutes, their team lead gets the notification.

This is how you write requirements that can be both estimated and accepted. It matters especially for bots and Mini Apps: their logic lives in the conversation, and without user flows the contractor has to fill in the gaps. Learn more about how we design state maps on our Telegram bot development page.

Priorities: MoSCoW

Tag every feature: Must (the product can't launch without it), Should (needed, but can wait a month), Could (nice to have), Won't (definitely not in this version). This tagging is the basis of the first product version; we covered how to choose features for launch in detail in our article on MVP development.

Non-functional requirements people forget

Features describe what the product does. Non-functional requirements describe how it does it. These are the ones that most often surface after launch, and they cost the most if they weren't agreed on in advance.

• Load: how many users you expect in the first month and in a year, and whether there are peaks (sales, mailings).
• Speed: target page load and bot response times; for websites, Core Web Vitals targets.
• Availability: acceptable downtime, and whether you need monitoring and on-call support.
• Security: what data is stored, who has access to it, whether two-factor authentication and an audit log are needed.
• Personal data: processing under 152-FZ, data localization in Russia, consents and a privacy policy.
• Hosting: your cloud, your own servers or an isolated network with no internet access.
• Support: browsers, iOS and Android versions, interface languages, accessibility for visually impaired users.
• Handover: documentation, credentials, a repository in your account, deployment instructions.

Example technical specification for a website

Below is a condensed example of a technical specification for a manufacturing company's website. It fits on two pages and is already enough to get an accurate estimate.

1. Goal: generate equipment quote requests from B2B customers; target of 40 qualified requests per month 3 months after launch.
2. Audience: engineers and procurement specialists at industrial companies, 70% visiting from desktop.
3. Roles: visitor; content manager (edits the catalog and news); administrator (access, settings).
4. Structure: home page, catalog of 6 categories and ~120 items, product page with a PDF spec sheet, case studies, about, contacts, blog.
5. Key user flow: a visitor finds an item via the filter → opens the product page → clicks “Request a quote” → fills in a 4-field form → the request goes to Bitrix24 and to the sales team's Telegram.
6. Integrations: Bitrix24 (lead creation), Yandex Metrica with goals, daily catalog export from 1C.
7. Design: brand book exists; a UX prototype and mobile-responsive layout are needed.
8. Non-functional requirements: page load under 2 seconds on 4G, technical SEO and structured data, hosting in Russia.
9. Acceptance: all flows from item 5 pass on the staging environment, forms reach the CRM, Lighthouse Performance score of 90+.

Notice what's missing: the words “modern”, “user-friendly” and “high-converting”. Instead there are numbers, roles, a user flow and criteria. With a document like this, contractors quote comparable prices, and you compare proposals rather than fantasies. To see what websites and web apps we build and what the work involves, visit our website development section.

Common spec mistakes and how to avoid them

Another trap is trying to describe every last button before there's a prototype. Interface details are faster and cheaper to settle on a clickable prototype: you see the screens, click through, make changes. The spec sets the frame; the prototype fills it in.

Online questionnaire: a spec without a blank page

The hardest part is getting started. That's why our website has an online questionnaire for writing a spec: it turns the structure above into a sequence of questions with hints and answer options. You don't have to write from scratch; most items are selected with buttons. The questionnaire has 7 sections:

1. About you: contacts, company, your role in the project.
2. About the product: product type, goal, stage, current stack, references and links to documents.
3. Users and roles: audience, roles, scale, geography, the user's problem.
4. Functionality: features, the must-have minimum, payments, integrations.
5. Platforms and design: where the product runs, design, branding, content.
6. Data, AI and security: whether AI is needed, data migration, security and hosting requirements.
7. Budget, timeline and process: budget, deadline and the reason for it, support, your involvement.

Right after submitting, you get a preliminary estimate. It's for reference: we give the exact cost after working through the spec together with you. Price benchmarks for all services are collected on our development pricing page.