How to Write a Technical Specification for a Website or Software Platform

A good technical specification describes the business goal, the users, the scope, the core processes, the functional and non-functional requirements, and the way the result will be accepted. It is not a list of ideas, and it does not require the client to design the software architecture. Its purpose is for the client and the vendor to share the same understanding of what is being built, why, and how it will be verified that it works.

This guide applies equally to a corporate website or online store and to a customer portal, CRM, ERP, marketplace, booking system or any other web-based software platform.

What is a technical specification?

A technical specification is a structured document that translates a business idea into clear, verifiable and prioritised requirements for the future digital product. It connects the needs of the business with the work of UX designers, software architects, developers, QA specialists and project managers.

A good specification answers at least the following questions:

• What problem are we solving?
• Who are the users and what must they be able to do?
• What is inside the project and what stays outside it?
• What data, roles, integrations and business rules are needed?
• What are the requirements for security, performance, accessibility and SEO?
• How will each important requirement be tested and accepted?
• Which assumptions, dependencies and risks could affect price or timeline?

In professional practice this is part of the wider discipline of requirements engineering. The international standard ISO/IEC/IEEE 29148:2018 describes processes and information items for requirements for systems and software. For most business projects, however, the client's specification does not need to reproduce the whole standard. What matters more is that the document is understandable, unambiguous and applicable to the specific project.

What is the difference between a brief, a technical specification and a contract?

The brief explains the idea, the technical specification defines the expected product, and the contract sets out the rights and obligations of the parties. The three documents complement each other, but they are not interchangeable.

A contract may reference an approved technical specification as an annex. The specification itself, however, is rarely sufficient to replace clauses on payment, code ownership, confidentiality, support or termination.

Does the client have to write the whole specification alone?

The client does not need to produce a finished software specification on their own. The client knows the business, its processes and constraints, while an experienced vendor should help translate them into user scenarios, business rules and verifiable requirements.

A practical working model is:

1. The client prepares a short brief and the available materials.
2. The vendor holds working sessions with the key stakeholders.
3. The team describes the processes, roles, data and integrations.
4. A UX specialist creates the information architecture, wireframes or a prototype where needed.
5. The technical team checks feasibility and risks.
6. Both sides approve the scope, priorities and acceptance criteria.

For a small presentational website this process can be fairly light. For an ERP, a marketplace or a platform with several roles, payments and external integrations, it is sensible to have a separate analysis and specification stage, often called Discovery.

What is the difference between a specification for a website and one for a software platform?

A website specification is oriented mainly towards content, structure, presentation, discoverability and conversions, while a software platform specification describes roles, states, business processes, data and rules. In practice many modern projects contain both parts.

For example, "the user submits an enquiry" is sufficient as an initial requirement for a simple website. For a B2B platform it must be specified which user, which fields they fill in, how those are validated, who receives the request, what status is created, who can change it and what notification is sent.

What structure should a technical specification have?

A working technical specification usually contains 12 connected parts: context, goals, users, scope, content or processes, functions, data, integrations, non-functional requirements, acceptance, project organisation and change management. Not every section has to be long, but each should be considered deliberately.

1. Context and business problem

Describe why the project exists, how work is done today and what is not functioning well. Do not start with "we want a modern website", because "modern" is not a verifiable requirement.

A more useful description is:

Today enquiries arrive by phone, email and several different contact forms. Some of them are not assigned to a salesperson in time. The new website must collect requests in a single format and send them to the CRM with source, selected service and consent to data processing.

2. Goals and success metrics

A goal describes the desired change in the business; functionality is only a means to achieve it. So "there should be a form" is a function; "reduce low-quality enquiries through pre-qualification" is a goal.

Suitable indicators may include:

• share of successfully submitted forms;
• number of qualified enquiries;
• request processing time;
• reduction in manual operations;
• percentage of completed registrations or payments;
• usage of a specific feature;
• time needed to publish new content;
• number of errors or support requests after launch.

Do not set arbitrary numbers just to have a KPI. Use the current baseline if one is available, and note how the result will be measured.

3. Users, roles and permissions

For every role it must be clear what its goal is, what data it sees and what actions it can perform. "Users and an administrator" is usually too general for a real platform.

Example roles:

• unregistered visitor;
• registered customer;
• employee or operator;
• team manager;
• accountant;
• partner or supplier;
• content editor;
• system administrator.

A "role × action" matrix is useful: view, create, edit, approve, delete, export. Constraints should also be specified — for example, a salesperson sees only their own customers, while a manager sees the whole team.

4. Scope and explicitly excluded work

The scope must describe both what is included in and what is excluded from the project. This is one of the strongest defences against mismatched expectations and uncontrolled expansion of the work.

Example:

Included: public website in Bulgarian and English, CMS, catalogue, enquiry form, CRM integration, migration of 120 pages and basic SEO migration.

Not included: product configurator, online payment, customer accounts, content translation, photography and automatic ERP synchronisation.

Add a list for a future phase as well. That way good ideas are not lost, but they are not mixed into the agreed MVP either.

5. Information architecture and content

For a website, describe the sitemap — the main pages, their hierarchy and the links between them. For each page type specify:

• purpose and audience;
• main content blocks;
• call to action;
• whether it is managed through the CMS;
• whether different languages are needed;
• who creates the text, photos, video and translations;
• whether there are special SEO fields;
• which data is structured and which is free text.

The phrase "the client provides the content" is not enough. It must be clear in what format, by what date, who processes it and who enters it.

6. User scenarios and business processes

A software platform is most clearly described through the sequence of actions, decisions and states that a real task passes through. Instead of just a list of screens, describe what happens from start to finish.

Example scenario for a request:

1. The customer selects a service and fills in a form.
2. The system validates the mandatory data and the consent.
3. A request is created with status "New".
4. The request is assigned automatically by region.
5. The responsible employee receives a notification.
6. The employee accepts or reassigns the request.
7. If no action is taken within the agreed period, a reminder is sent and a manager is notified.
8. All changes are recorded in a history.

After the main flow, describe the exceptions: duplicate request, missing data, unavailable external system, declined payment, expired deadline or an action without sufficient permissions.

7. Functional requirements

A functional requirement describes what the system must be able to do in a specific context. Use clear verbs and state the role, input data, rules and result.

Weak requirement:

There should be user management.

Better requirement:

The administrator can create, deactivate and assign roles to employees. A deactivated employee cannot log in to the system, but their previous actions remain visible in the history.

Another useful format is the user story:

As a team manager, I want to see the unprocessed requests of my employees so that I can reassign a request when someone is absent.

The user story does not replace the details. It must be accompanied by rules and acceptance criteria.

8. Acceptance criteria

Acceptance criteria turn a general expectation into a verifiable result. They should allow the client, the developer and the QA specialist to reach the same conclusion on whether the requirement has been met.

Example for a contact form:

• the form contains name, company, email, phone, selected service and message;
• the email is mandatory and is validated;
• without the mandatory consent checked, the form is not submitted;
• after successful submission the user sees a confirmation;
• the request is stored in the admin panel and sent to the CRM;
• if the CRM integration is unavailable, the request is kept and retried, without the user having to fill in the form again;
• the submission is tracked in the analytics system as an event.

Criteria such as "it should be convenient", "it should work fast" and "it should look professional" cannot be accepted unambiguously without additional conditions.

9. Data, documents and reports

The specification should already describe the main business objects, the critical fields and the relationships between them. The client does not have to create a technical database schema.

For each important object state:

• how it is created and by whom;
• which fields are mandatory;
• which values are calculated automatically;
• what statuses it has;
• who can change or delete it;
• how long it is retained;
• whether versioning or history is needed;
• whether it can be imported and exported;
• which reports it appears in.

If reports are needed, attach a sample table with columns, filters, grouping and the expected export format. "There should be all kinds of reports" does not allow a reliable estimate.

10. Integrations and external dependencies

Every integration must state the system, the direction and frequency of exchange, the data, the responsibility and the behaviour on error. The vendor's name alone is not enough.

Record:

• whether current API documentation is available;
• who provides test accounts and keys;
• which system is the source of truth for each type of data;
• whether the exchange is real-time, periodic or manual;
• how duplicate records are handled;
• what happens during temporary unavailability;
• who monitors and fixes errors;
• whether there are limits, fees or contractual restrictions from the third party.

With payments, couriers, ERP, CRM, accounting software, electronic signatures and external identification, the unknowns around the integration can significantly change the estimate.

11. Non-functional requirements

Non-functional requirements define the qualities and constraints of the product — security, performance, reliability, accessibility, compatibility and maintainability. They should not be left as an implied "good practice" when they matter for acceptance.

Performance and capacity

State the expected users, peak periods, data volume, file sizes and critical operations. A requirement such as "the page should load within X seconds" must specify the test environment, device, network, page and measurement tool.

Security

Describe at least authentication, roles and permissions, protection of sensitive data, logging of important actions, backup, recovery, secrets management, updates and incident response. For higher-risk web applications, OWASP ASVS can serve as a verifiable basis for requirements and tests of technical security controls.

Personal data and GDPR

The specification must state what personal data is collected, for what purpose, on what legal basis, for how long and who has access. The European Commission summarises purpose limitation, data minimisation, storage limitation, security and accountability among the key principles. This means GDPR should not be reduced to adding a checkbox and a "Privacy Policy" page after development. See the principles of personal data processing under the GDPR.

Accessibility

If the project has web accessibility requirements, name a specific standard and level, for example WCAG 2.2 AA, and how compliance will be checked. WCAG 2.2 contains technology-neutral and testable criteria for the accessibility of web content. An automated test alone is not sufficient for all criteria.

Compatibility

Define the supported browsers, devices, minimum resolutions and operating systems according to the real audience. "It should work everywhere" is not a realistic test scope.

Reliability, backups and recovery

For a business-critical platform, state the expected availability, the acceptable data loss, the target recovery time, the backup frequency and the responsibility for monitoring. These parameters directly affect infrastructure and price.

12. SEO, analytics and migration

For a new website, or the replacement of an existing one, SEO requirements and migration must be part of the specification before development. After launch it is often too late or more expensive to recover missed URLs, metadata, internal links and measurement.

Specify:

• URL structure and rules;
• title, meta description, canonical and robots settings;
• XML sitemap and language versions;
• structured data where applicable;
• redirect management;
• an "old URL → new URL" list for migration;
• migration of content, images and files;
• analytics tools, events and conversions;
• requirements for the cookie consent mechanism;
• post-launch checks and error monitoring.

Google recommends permanent server-side redirects, such as HTTP 301 or 308, when a URL has moved permanently. The redirect map should therefore be a concrete part of the migration plan, not a task "if time allows". See Google's documentation on redirects.

How are design and user experience described?

The specification should describe the goals, audience, content and constraints of the design, but it does not need to replace the UX process or the visual design. The sentence "make it like website X" is a reference, not a sufficient requirement.

State:

• existing brand identity and files;
• desired perception and unsuitable visual directions;
• reference websites or products and exactly what you like about them;
• key user tasks;
• mandatory components and states;
• requirements for responsive behaviour;
• language and content constraints;
• the process for presenting and approving a design concept;
• the number and scope of included revisions.

An interactive prototype often reveals missing states and awkward processes more cheaply than when code has already been written. It should not, however, hide undescribed business rules.

How are the MVP and priorities defined?

An MVP is the smallest version that completes a core user process and allows a key business hypothesis to be tested. MVP does not mean all planned features built in a hurry or with compromises on security.

A practical prioritisation method is:

• Must have — without it the core process cannot complete or the product cannot launch;
• Should have — high value, but a temporary workaround exists;
• Could have — a useful improvement that can wait for a later phase;
• Won't have now — consciously excluded from the current version.

For every "Must have", ask: "What exactly becomes impossible if this feature is missing?" If there is no clear answer, the priority probably needs to be reconsidered.

How detailed should the technical specification be?

The specification should be as detailed as necessary for estimation, development and acceptance without critical assumptions. Length in itself is not a measure of quality.

A simple corporate website can be described with a clear structure, page types, content responsibilities, forms, CMS, SEO and acceptance criteria. A complex platform requires processes, roles, statuses, rules, integrations, data models, exceptions and non-functional requirements.

A sign that the detail is insufficient is when different vendors can quite reasonably imagine different products. A sign of over-specification is when the document prescribes internal technical decisions without a business reason and blocks a better implementation.

Can an exact price and timeline be given from the specification?

The accuracy of an estimate depends on the clarity of the scope, the unknowns and the external dependencies. A short brief usually allows an indicative range; an approved specification and prototype allow a significantly more reliable estimate.

Price and timeline are most often changed by:

• the number of roles, processes and unique screens;
• the complexity of the business rules;
• the availability and quality of API documentation;
• migration and the quality of legacy data;
• requirements for security, audit and regulatory compliance;
• load and availability;
• the number of languages and the volume of content;
• the need for custom design and user testing;
• the speed of feedback and approvals;
• clearly defined acceptance.

If there are critical unknowns, the correct approach is to investigate them first through Discovery, a technical prototype or an integration test. A fixed price on an unclear scope does not remove the risk — it usually just hides it in assumptions, contingency or future change requests.

How are changes managed after the project starts?

Changes are normal, but they must have a visible effect on scope, budget, timeline and dependencies. "Agile" does not mean unlimited features at a fixed price.

A good change process includes:

1. a short description and reason;
2. business priority;
3. analysis of the affected screens, data, integrations and tests;
4. an estimate of price and timeline;
5. a decision: swap for another item, add to the current phase, or postpone;
6. written approval;
7. an update of the specification, the backlog and the acceptance criteria.

The specification must have a version, a date and a history of significant changes. Otherwise different people may work from different "latest" copies.

What are the most common mistakes in a website or software specification?

The most common mistake is describing a list of features without business context, rules and acceptance criteria. The project then looks clear until design and development begin.

Other typical omissions are:

• "modern", "intuitive" and "fast" without a measurable criterion;
• no explicitly excluded work;
• mixing the first version with the long-term vision;
• missing roles, permissions and negative scenarios;
• integrations mentioned in a single sentence;
• unclear responsibility for content and migration;
• missing mobile and empty states, errors and confirmations;
• GDPR, security, backups and accessibility left for the end;
• no analytics plan and defined conversions;
• estimating by number of pages when the real complexity is in the processes;
• acceptance "by feel" instead of by scenarios;
• choosing a specific technology without a proven need;
• no change procedure and no single person responsible for approval.

Example of a short technical specification for a corporate website

The following example shows a minimal working structure, not a universal specification for every website. The real document must be adapted to the business, the content and the integrations.

Context and goal

The company offers B2B services in Bulgaria and receives enquiries mainly through referrals. The new website must clearly present the services, show relevant projects and collect structured enquiries.

Audiences

• owners and chief executives;
• operations and IT managers;
• potential employees.

Scope

• home page;
• services and a detail page per service;
• industries;
• projects and a detail page per project;
• about the company;
• team;
• blog;
• careers;
• contact;
• Bulgarian and English versions;
• admin panel for content management.

Core functions

• enquiry form with topic selection;
• job application form with CV upload;
• project filtering;
• SEO field management;
• analytics and CRM integration;
• 301 redirect management.

Acceptance criterion — enquiry

When a visitor fills in valid mandatory fields and gives the required consent, the system creates a record, sends the information to the CRM, notifies a designated recipient and shows a confirmation. If the CRM returns an error, the request remains stored for reprocessing.

Out of scope

• online payments;
• customer accounts;
• automatic translation;
• creating a new visual identity;
• writing and translating all texts.

Example requirement for a software platform

For a software platform, a single requirement should cover role, condition, action, rules, result and exceptions. For example:

Feature: expense approval

User story: As a manager, I want to approve the expenses of the employees in my department so that I can control the budget before payment.

Business rules:

• an employee can submit an expense with category, amount, currency, date, cost centre and a document;
• the system selects the approver based on department and amount;
• the requester cannot approve their own expense;
• above a defined threshold a second approval is required;
• a rejection requires a reason;
• every action is recorded with user, date and time.

Acceptance criteria:

• a valid request receives the status "Pending approval";
• the correct manager receives a notification;
• an unauthorised user cannot open or approve the request;
• on approval the system records the action and moves to the next step;
• on rejection the request is returned to the employee with the reason visible;
• the history cannot be edited by a standard user.

This format provides a far more reliable basis for UX, development and QA than the sentence "expense module with approvals".

Ready-to-use technical specification template

The following template can be copied and filled in for a website, an online store or a software platform. Sections that do not apply can be marked as such rather than deleted without review

# Technical specification: [project name]

## 1. Version and owners
- Version:
- Date:
- Document owner:
- Approvers:

## 2. Context
- How does the process work today?
- What problem must be solved?
- Why is the project needed now?

## 3. Goals and metrics
- Business goals:
- User goals:
- Metrics and how they are measured:

## 4. Audiences and roles
- Role:
- Main goal:
- Visible data:
- Permitted actions:
- Constraints:

## 5. Scope
### Included
- ...

### Out of scope
- ...

### Future phases
- ...

## 6. Structure or modules
- Pages/modules:
- Navigation and links:
- Core objects and statuses:

## 7. User scenarios
### Scenario: [name]
1. Precondition
2. Actions
3. Decisions and rules
4. End result
5. Errors and exceptions

## 8. Functional requirements
### Requirement: [name]
- Role:
- Action:
- Input data:
- Business rules:
- Result:
- Acceptance criteria:

## 9. Content and languages
- Content types:
- Source and owner:
- Format and delivery deadline:
- Migration:
- Translations:

## 10. Data and documents
- Core objects:
- Mandatory fields:
- Retention periods:
- History and audit:
- Import/export:

## 11. Integrations
- External system:
- Purpose:
- Direction and frequency of exchange:
- Data:
- Documentation and access:
- Behaviour on error:
- Responsible party:

## 12. Non-functional requirements
- Performance and load:
- Security:
- Personal data:
- Accessibility:
- Browsers and devices:
- Backup and recovery:
- Monitoring and logging:

## 13. UX/UI
- Brand materials:
- References and specific liked elements:
- Key user tasks:
- Responsive design requirements:
- Approval process:

## 14. SEO and analytics
- URL rules:
- Metadata and structured data:
- Redirect map:
- Events and conversions:
- Tools and access:

## 15. Testing and acceptance
- Types of tests:
- Test environment and data:
- Owners:
- Acceptance procedure and deadline:
- Launch criteria:

## 16. Launch, training and support
- Environment and infrastructure:
- Migration plan:
- Training and documentation:
- Warranty period:
- Support and SLA:

## 17. Priorities, budget and timeline
- Must / Should / Could / Won't:
- Budget or range:
- Target date and the reason for it:
- Critical dependencies:

## 18. Assumptions, risks and open questions
- Assumptions:
- Risks:
- Unknowns:
- Decision and owner for each question:

## 19. Change management
- Request channel:
- Estimation method:
- Approver:
- Version history:

Checklist before sending to a vendor

Before requesting a quote, check whether:

• The business problem and goal are clear;
• All real user roles are described;
• The core processes have a start, an end and exceptions;
• What is in and out of scope is distinguished;
• The MVP is separated from future ideas;
• The important features have acceptance criteria;
• Responsibility for content, translations and migration is assigned;
• Integrations have documentation, access and behaviour on error;
• Security, GDPR, accessibility and backups have been discussed;
• SEO migration and analytics are included;
• There is a test environment and an acceptance process;
• Launch, training and support are specified;
• Unknowns and assumptions are visible;
• There is one responsible person who makes final decisions;
• Changes after approval have a clear process.

Can AI write the technical specification for you?

AI can help with structure, questions, a first draft and spotting gaps, but it cannot by itself confirm the organisation's real processes, priorities and constraints. If the input is incomplete, the result can look professional and at the same time contain false assumptions.

Use AI for:

• turning meeting notes into a structured draft;
• generating questions for stakeholders;
• proposing negative scenarios and acceptance criteria;
• consistent naming of roles, statuses and objects;
• finding contradictions between sections.

The document should then be reviewed by the business owner of the process, a UX specialist, a technical architect and QA, depending on the project's complexity. AI should not invent regulatory requirements, integration constraints or decisions on behalf of the people who are accountable for the project.

How does Sirius Software approach an unclear project idea?

When an idea is not detailed enough, the right first step is not an arbitrary fixed-price quote but a structured clarification of the product. At Sirius Software we review the business goals, roles, processes, data, integrations and risks, and then shape the scope, the approach and a realistic basis for an estimate.

Depending on the project, the result may include:

• a map of the processes and user roles;
• functional scope and MVP priorities;
• information architecture;
• wireframes or an interactive prototype;
• technical analysis of the integrations;
• acceptance criteria;
• phases, dependencies, a budget range and a development plan.

Sirius Software builds websites and software solutions, including custom software, ERP and CRM platforms, online stores and integrations with external systems.

If you have an idea, an old document or a list of features, you do not need to turn it into a perfect technical specification on your own first. Send the information you have through the Sirius Software contact form. We will discuss what is already clear enough, which unknowns affect the estimate and what analysis is needed before development.

Frequently asked questions

Is a technical specification mandatory for a small website?

Yes, but it does not have to be a long document. A small website needs at least goals, structure, content types, functionality, responsibilities, technical requirements and acceptance criteria. A short but specific specification is more useful than dozens of pages of general phrases.

Who should approve the specification?

The specification should be approved by a person with the authority to make business decisions, as well as by the people responsible for key processes, content, IT, security or legal requirements, depending on the project. One final product owner should resolve contradictions.

Should I name a technology in the specification?

Name a technology when there is a real constraint — existing infrastructure, an internal standard, a need for compatibility, or support by a specific team. If there is no such reason, it is better to describe the requirements and ask the vendor to propose and justify the technical solution.

Can the technical specification change?

Yes. The specification should be managed by versions, and every significant change should be assessed for its impact on scope, price, timeline, design, data and tests. The problem is not change, but invisible change without a shared decision.

What should I send if I do not have a specification yet?

Send a short description of the business and the problem, the current process, the main users, the mandatory features, the existing systems, the desired timeline, a budget range and examples you like. That is enough for a first meeting and for planning the next step.

Can I compare quotes on final price alone?

Not reliably, if the quotes rest on different assumptions. Compare the included scope, exclusions, design process, migration, integrations, tests, infrastructure, warranty, support and acceptance criteria. A lower price may simply mean that part of the necessary work is not included.

Conclusion

A good technical specification does not have to foresee every future decision; it has to remove the critical ambiguity around the product's goal, scope and acceptance. Start from the business problem and the user processes, separate the MVP from future ideas, describe the important rules and exceptions, and turn expectations into verifiable criteria.

That way the specification does not just help you get a quote. It reduces the risk of building a perfectly working product that solves the wrong problem.

About the author

Georgi Papucharov is the founder of Sirius Software - a Bulgarian software company that has been building custom web systems, CMS solutions, e-commerce platforms, AI integrations and connections to external business systems since 2011. Sirius Software is certified to ISO/IEC 27001:2022.