How to Write a Technical Specification for Software Development

Why a technical specification matters

A technical specification (a spec, or terms of reference) is the document that turns a client's idea into a set of verifiable requirements for a product. Without it, the two sides almost always picture the project differently: the client holds one image in mind, the development team builds another, and at the demo it turns out that half of the expected functionality was "implied" but written down nowhere.

In the Uzbekistan market this is especially painful. A large share of development requests comes from companies with no in-house IT team: retail, logistics, private clinics, education centers, fintech startups. They know their business well but struggle to formulate software requirements. As a result they agree "verbally", and later argue about whether Payme and Click integration was part of the original quote.

A spec solves three problems at once: it fixes the scope of work (and therefore the budget), it provides acceptance criteria, and it protects both parties legally. It is an attachment to the contract that can be referenced when disagreements arise.

What the structure of a spec should include

A good spec does not need to be thick. It needs to be complete and unambiguous. A minimal working composition looks like this:

• Goal and context. What business problem we are solving, who the users are, and what counts as success. Without this the team cannot suggest reasonable alternatives.
• Roles and access rights. Who the administrator, operator, and client are, and what each of them can and cannot do.
• Functional requirements. A description of screens and scenarios: what happens on each action, which fields are required, what validations apply. User stories are the most effective format.
• Non-functional requirements. Load, response time, security, interface languages (for Uzbekistan almost always Uzbek and Russian, often English), hosting requirements.
• Integrations. Payment systems (Payme, Click, Uzum), SMS gateways (Eskiz, Play Mobile), 1C, Soliq/e-invoicing, Telegram. Specify API versions and who provides access credentials.
• Design and brand book. Whether ready-made mockups and a corporate style exist, or whether design is part of the work.
• Stages, deadlines and acceptance criteria. What counts as a finished deliverable for each stage.

Who writes the technical specification

A common misconception is that "the programmer should write the spec". In practice responsibility is shared. The business side answers what and why, the technical side answers how.

The ideal arrangement: the client prepares business requirements (goals, processes, constraints), and the team's analyst or project manager turns them into a technical specification with screens, scenarios and integrations. The document is then reviewed and approved by the client before signing.

If the client has no internal expertise, it is reasonable to commission the spec as a separate paid service, as a small stage before the main development. This is cheaper than reworking a finished product, and it yields a document you can take to other vendors to compare prices.

Common mistakes in technical specs

Over the years the same problems repeat:

• Vague wording. "User-friendly interface", "fast performance", "modern design" are not requirements and cannot be tested. Replace them with something measurable: "a list of 1000 records opens within 2 seconds".
• No negative scenarios. Only the happy path is described, while failed payments, cancelled orders or duplicates are left unaddressed. This is exactly where most bugs and rework are born.
• No priorities. When everything is "critically important", budget and deadlines explode. Separate the mandatory (MVP) from the desirable.
• Ignoring local realities. Forgetting multilingual support, the quirks of local payment providers, and e-invoicing and reporting for Soliq. These surface at the end and blow the schedule.
• A spec with no versioning. Requirements change, and that is normal. But changes must be recorded in writing as addenda, otherwise a dispute over extra payment is inevitable.

How to accept the result against the spec

Acceptance is not "I looked and it seems to work". It is a comparison of the finished product against the criteria in the spec. For it to go smoothly, acceptance criteria must be written in advance, back when the document is being agreed.

A working acceptance procedure:

• The team deploys a version to a test environment that the client can access.
• The client walks through the scenarios from the spec, marking each item as "accepted / comment".
• Comments are split into bugs (non-compliance with the spec, fixed by the team within the quote) and new wishes (changed requirements, formalized as additional paid work).
• Once bugs are closed, the stage acceptance act is signed.

This is precisely why a spec benefits both sides. The client is protected from "unfinished" work, and the team is protected from endless free revisions driven by expanding expectations.