DESAmedia ·

Short answer

A technical specification is the document in which the client describes what a system must do, who will use it, which other systems it must exchange data with and how everyone will know the work is done. A good specification describes needs and outcomes, not a particular technology. It covers goals, user roles, processes, functional and non-functional requirements, integrations, data migration, acceptance criteria and support terms. In Lithuanian public procurement, Article 37 of the Law on Public Procurement also applies: the specification must preserve competition, and specific brands or models may only be named as an exception, followed by the words "or equivalent". Below you will find a template you can copy and a short, fictional example.

Why a specification matters

A software project without a specification usually starts with a sentence like "we need a system for orders". Every supplier reads that sentence differently, so you end up with three proposals you cannot compare. One prices a simple form with a table, another a system with accounting integration and a customer self-service area, and the third offers an off-the-shelf product. The prices differ several times over, not because of hourly rates, but because each supplier estimated a different piece of work. We looked at what drives the price in How much does custom software development cost.

A specification solves three problems:

  • Comparable proposals. Every supplier estimates the same list of work, so the differences come down to price, timeline and approach.
  • A clear scope. The contract can refer to a document rather than to people's memories of meetings. When a new request comes up, it is clear whether it is a change or work already agreed.
  • A basis for acceptance. When the work is finished, you check it against criteria agreed in advance, not against an impression.

The client benefits too. Writing a specification often reveals that different departments understand the same process differently, or that part of the problem can be solved without a new system at all. If you are still deciding whether you need a system, start with Excel or a custom system? 7 signs.

What a technical specification should cover

The nine parts below fit most business systems: a CRM, an order management system, a B2B portal or an internal back-office tool. In a smaller project some of them will be only a few sentences long.

1. Goals and measures of success

Start with why the system is needed and how you will know it has paid off. "Automate order intake" is a direction, not a goal. A goal sounds more like this: "an order placed in the customer portal reaches the accounting system without anyone retyping it, and the account manager sees its status in one place". If you know how long the process takes today or how many errors occur, write the numbers down. They become your baseline after launch.

In the same section, describe what is out of scope. A list of "not in this phase" items prevents more misunderstandings than any other section.

2. Users and roles

List everyone who will use the system: account managers, warehouse staff, accounting, management, customers, partners. For each role, state what it does in the system, what it can and cannot see, and roughly how many users there will be. A permissions table (role by action) later becomes one of the most useful testing tools.

3. Processes

Describe how the work is done today and how it should work with the new system. A simple list of steps is enough: who starts the action, what data is passed on, who approves, and what happens when something fails. If you have sample documents, reports or spreadsheets, attach them. A real order PDF or the actual Excel file tells a developer more than a page of text.

4. Functional requirements

Functional requirements describe what the system does: which actions users take and how the system responds. Give every requirement an ID (for example FR-01) so it can be referenced in the contract, the estimate and the acceptance tests. Write from the user's point of view: "An account manager can change the order status, and the customer receives an email about the change."

5. Non-functional requirements

Non-functional requirements describe how well the system must work. They are the ones most often left out, and later they cause the biggest disputes. The quality model in the international standard ISO/IEC 25010:2023 makes a good checklist. It defines nine product quality characteristics: functional suitability, performance efficiency, compatibility, interaction capability (previously called usability), reliability, security, maintainability, flexibility and safety.

Area What to describe Example
Security Login, permissions, audit log, encryption "Every change of order status is logged: who, when, the old value and the new value."
Personal data Which data is processed, how long it is kept, who can see it "Contact details of inactive customers are anonymised after the agreed period."
Accessibility WCAG level and which interfaces it applies to "The customer portal meets WCAG 2.1 AA."
Performance Response time, concurrent users, data volume "The order list with 50,000 records opens in under 2 seconds."
Reliability Availability, backups, recovery "Backups run daily and a restore is tested every quarter."
Maintainability Documentation, tests, handover of code "The code is kept in a repository owned by the client."
Compatibility Browsers, devices, languages "The portal works on mobile phones and is available in Lithuanian and English."

On personal data, keep Article 25 of the GDPR in mind: data protection has to be built in at the design stage, not added after launch. Article 32 requires appropriate technical and organisational security measures. Both are far easier to deliver when they are written into the specification.

Accessibility is not mandatory for every system. Legal requirements apply to public-sector websites and apps and to certain consumer services, such as e-commerce. We explained who they apply to and what WCAG 2.1 AA means in practice in WCAG and the European Accessibility Act. Even where it is not required, it is worth specifying accessibility for customer- and partner-facing interfaces, because fixing it later costs more.

6. Integrations

For every external system, state what data flows, in which direction, how often, and which system is the "source of truth". For example: products and stock levels come from accounting every 15 minutes, orders go to accounting as soon as they are confirmed, and customer contacts are maintained only in the new system. Always name the version of the software you use (for example Rivilė GAMA or Rivilė ERP), because it determines which kind of connection is possible. We covered what can realistically be done with the most common Lithuanian accounting systems in Integrating Rivilė, Directo and Agnum.

Do not forget the failure case: what should happen if the accounting system is unreachable, and who gets notified.

7. Data and migration

If the system replaces spreadsheets or an old application, describe which data must be moved, how much of it there is, what condition it is in and who is responsible for cleaning it up. Data migration often takes longer than expected, because old data turns out to contain duplicates, empty fields and inconsistent formats. State whether you need the full history or only active records, and when the final migration will happen before go-live.

8. Acceptance criteria

Acceptance criteria answer the question "when is the work done?". They are easiest to write as testable scenarios: "When a customer submits an order in the portal, it appears in the accounting system within 5 minutes with the same quantities and prices." Also agree how long you will have for testing, what counts as a critical defect and what happens if one is found. We collected the questions worth raising with a supplier before signing in How to choose a software development partner.

9. Support, warranty and SLA

A system lives for years after launch, so the specification should cover the warranty period, response times by severity, how updates and security patches are handled, backup requirements, and what you receive if the relationship ends: code, documentation and access credentials. If the intellectual property rights to the code are to be transferred to you, say so explicitly. In Lithuanian public procurement, Article 37 of the Law on Public Procurement expressly allows the specification to state whether intellectual property rights must be transferred.

How to write a good requirement

The requirements engineering standard ISO/IEC/IEEE 29148:2018 lists the characteristics every requirement should have. In practice, four matter most: a requirement should be unambiguous (it can only be read one way), verifiable (you can prove it has been met), singular (one requirement per statement) and necessary (the system's purpose cannot be achieved without it).

Weak requirement Why it fails Better wording
"The system must be fast." Cannot be verified "An order opens in under 2 seconds when the system holds 50,000 orders."
"A user-friendly, modern interface." Everyone reads it differently "An order can be placed on a phone, without zooming, in no more than 4 steps."
"Integration with accounting." Data and direction unclear "A confirmed order is sent to accounting as a sales document within 5 minutes; stock levels are updated from accounting every 15 minutes."
"Reports as needed." Scope undefined "A monthly sales report by customer and product group, exportable to Excel."
"The system must be secure and meet all requirements." Unverifiable and undefined "Administrators sign in with two-factor authentication; every data change is logged."

One more habit worth adopting: avoid "etc.", "as needed" and "if required". Each of them marks a spot where a pricing dispute will appear later.

How detailed should it be?

A specification should describe what the system does and what results you expect, not how to build it. The client knows the process best; the developer knows the technology. Prescribing database tables or a programming language without a good reason narrows your choice of suppliers and makes you responsible for technical decisions.

A useful test: the specification is detailed enough when two different suppliers would estimate a similar amount of work after reading it. Screen designs, button colours and exact field layouts are usually unnecessary. It is enough to say what data a screen shows and which actions it allows.

Prioritise your requirements. A widely used approach is the MoSCoW method: Must have (the system is pointless without it), Should have (important, but a temporary workaround exists), Could have (nice to have) and Won't have this time (deliberately postponed). Priorities let you agree on the first release and stay within budget when it turns out that not everything fits.

Public procurement vs a private project

The content is much the same in both cases, but in the public sector the specification becomes a procurement document governed by law. The points below refer to Lithuania's Law on Public Procurement (Viešųjų pirkimų įstatymas).

Question Private project Public procurement
Legal basis Freedom of contract Article 37 of the Law on Public Procurement
Naming products and brands Allowed Only as an exception, with "or equivalent" added to each reference
Talking to suppliers Discuss and refine freely Market consultations are announced in CVP IS; information must be available to all
Changes after signing By agreement between the parties Without a new procurement, only in the cases set out in Article 89
Accessibility Depends on the type of service Procurements intended for natural persons should take the needs of people with disabilities into account

The provisions of the Law on Public Procurement that matter most here:

  • Competition. The technical specification must ensure competition and must not discriminate between suppliers (Article 37(3)).
  • Functional requirements. The subject of the procurement may be described through the desired outcome or functional requirements, which must be precise enough for suppliers to prepare suitable bids (Article 37(4)). For an IT system this is usually the most suitable approach.
  • "Or equivalent". A specific model, brand or source may only be named when the subject cannot be described any other way, and only followed by the words "or equivalent" (Article 37(5)). The Public Procurement Office (VPT) has clarified that the words must be added to every such requirement: a general clause in the tender documents does not replace them.
  • Accessibility. Except in justified cases, specifications for procurements intended for natural persons should take into account accessibility for people with disabilities and design for all users, and any mandatory requirements must be applied (Article 37(2)).
  • Contract changes. A procurement contract can only be changed without a new procedure in the cases listed in Article 89. One of them covers changes or options that were described clearly, precisely and unambiguously in the procurement documents in advance. If you plan to build the system in phases, describe the possible extensions (for example, extra modules or integrations) in the tender documents.
  • Market consultations. Before a procurement, the contracting authority may consult market participants, and the invitation is published in CVP IS, the central public procurement system (Article 27). In some cases they are mandatory, for example when the last similar advertised procurement in the previous 12 months received no suitable bids or only one. If a supplier helped prepare the specification, the contracting authority must take measures to keep competition fair, such as sharing the same information with other bidders and setting a sufficient deadline for bids.

State, register and internal administration information systems are also subject to a separate procedure. Under the Description of the Procedure for Establishing, Developing, Updating, Restructuring and Liquidating Information Systems (approved by Government Resolution No. 349 of 15 May 2024), a technical description (specification) of the information system must be prepared before development starts and agreed with the authorised institution. In that case the procurement specification has to be consistent with it.

You can read more about our work with public bodies on our public sector page.

The discovery phase: writing the specification with a developer

Not every organisation has someone who can write a specification. In that case there are two routes.

Route one: a paid discovery phase. You hire a supplier for the analysis only. They talk to users, review your existing files and systems, map the processes and produce a specification with an estimate. The result is a document you own and can use to choose a developer, even if you later pick a different supplier. In a private project this is usually the fastest way to an accurate price.

Route two: specification and procurement separately. In the public sector, analysis can be bought as a separate service and development procured later on the basis of the finished specification. Keep the Article 27 rule mentioned above in mind: if the supplier who wrote the specification bids for the development contract, the contracting authority must make sure the information they hold gives them no advantage, and the supplier may be asked to justify in writing that their earlier involvement did not distort competition.

Either way, involve the people who will use the system every day. Management's vision and the way work actually gets done often differ.

Common mistakes

  • A solution instead of a problem. "We need a mobile app" instead of "drivers must record deliveries without a paper delivery note". The first version rules out solutions that might be cheaper.
  • No out-of-scope list. If the boundary is not written down, each side imagines its own.
  • Forgotten non-functional requirements. Performance, accessibility, backups and permissions surface only during testing, when they are most expensive to add.
  • Integrations described in two words. "Integration with accounting" can mean a daily file import or a real-time two-way connection. The price differs several times over.
  • Data migration left until the end. Cleaning old data also takes the client's staff time, and nobody planned for it.
  • Copying the old system. A specification that describes the current application with all its workarounds carries old habits into the new system.
  • Naming a specific product in a public tender without "or equivalent", or setting requirements only one supplier can meet. Both invite procurement disputes.
  • No acceptance criteria. Without them it is hard to insist that defects be fixed.

Technical specification template

Copy this outline and fill it in. In a small project some sections will be a few lines long; in a large system each may become a separate annex.

  1. General information: project name, client, responsible people, document version and date.
  2. Current situation and problem: how the work is done today, what does not work, what it costs (if known).
  3. Goals and measures of success: what you want to achieve and how it will be measured after launch.
  4. Scope: what is included and what is deliberately excluded.
  5. Users and roles: list of roles, approximate number of users, permissions table.
  6. Processes: "as is" and "to be" descriptions of the key processes, with sample documents attached.
  7. Functional requirements: numbered (FR-01, FR-02...), each with a priority (Must, Should, Could, Won't).
  8. Non-functional requirements: security, personal data, accessibility, performance, reliability, compatibility, maintainability.
  9. Integrations: for each system: data, direction, frequency, source of truth, error handling, available interfaces.
  10. Data and migration: sources, volumes, data quality, responsibilities, migration timing.
  11. Acceptance criteria: acceptance scenarios, testing period, defect classification.
  12. Deployment and training: environments (test, production), user training, documentation.
  13. Support, warranty and SLA: warranty period, response times, updates, backups, exit terms.
  14. Rights and ownership: intellectual property rights to the code, licences, data processing agreement.
  15. Constraints and assumptions: budget range, deadlines, mandatory technologies or infrastructure (only with a good reason).
  16. Annexes: sample documents, reports, descriptions of existing systems, interface documentation.

Technical specification example: an order management portal

Below is a shortened extract from a specification. The company and all figures are fictional. The example shows the level of wording, not the scope of a real project.

Current situation. Example Ltd is a building materials wholesaler serving around 300 business customers. Orders arrive by email and phone, and account managers retype them into Rivilė GAMA. Customers call to ask about order status, and retyping leads to errors in quantities and prices.

Goals.

  • Customers place orders themselves, seeing their own prices and stock levels.
  • Orders reach the accounting system without being retyped.
  • Customers can see order status and invoices themselves.

Out of scope: warehouse management, card payments, a mobile app.

Roles: customer (around 300 companies, up to 3 users each), account manager (6), accounting (2), administrator (1).

Functional requirements (extract).

ID Requirement Priority
FR-01 A customer signs in and sees only their own company's prices, orders and invoices. Must
FR-02 A customer can build an order from the catalogue or repeat a previous order. Must
FR-03 The customer company's administrator can set which users approve orders. Should
FR-04 An account manager sees all orders of their customers and can change their status. Must
FR-05 When an order's status changes, the customer receives an email. Should
FR-06 A customer can download invoices as PDF. Could

Non-functional requirements (extract).

  • NFR-01: the customer portal meets WCAG 2.1 AA and works on mobile phones.
  • NFR-02: every change to an order is recorded in an audit log visible to the administrator.
  • NFR-03: the database is backed up daily and backups are kept for 30 days; a restore is tested before launch.

Integration with Rivilė GAMA.

  • Products, prices and stock: from Rivilė to the portal every 15 minutes. Rivilė is the source of truth.
  • Confirmed orders: from the portal to Rivilė within 5 minutes, as a sales order document.
  • If Rivilė is unreachable, orders are queued and the administrator is notified.

Data migration. Active customers and their contacts are migrated from Rivilė. Order history is not migrated.

Acceptance criterion (example). When a customer submits an order with 10 line items, a sales order with the same quantities and the customer's prices appears in Rivilė within 5 minutes, and the order status in the portal changes to "Accepted".

A document like this might run to 10-20 pages. That is enough for several suppliers to submit comparable proposals and for you to know exactly what you will check when accepting the work.

What to do next

Start with three things: write down the goals and the out-of-scope list, list the roles, and gather sample documents and spreadsheets. That is already enough to start talking to suppliers. If you would like us to prepare the specification together with your team, that is what our IT consulting and system design service is for: process analysis, requirements, an integration map and an estimate you can use with any developer. You can send us your questions via the contact page.

Sources