We develop technical specifications for websites that prevent client dissatisfaction. As engineers with a decade of experience, we've prepared over 50 TS for online stores, services, and portals. A common client complaint: 'This is not what I wanted.' This happens due to poor specification. Our approach: detailed analysis, formalized requirements, and versioning in Git. A good TS is a communication tool between the client, developers, and testers. It defines what will be built, how it looks, and how it is verified. Without a TS, a project descends into chaos. Our services for drafting a TS start at $1,500 for simple projects and can reach $5,000 for complex e-commerce platforms, saving you thousands in rework costs. Contact us for an audit of your project — we'll turn chaotic wishes into clear documentation.
The Purpose of a Technical Specification
The main mistake in a TS is describing the interface instead of behavior. 'A blue button in the right corner' is not a TS. But 'When the "Place order" button is clicked, the system creates an order with status draft, reserves the product, sends a confirmation email, and redirects to /orders/{id}' — that is a TS.
A quality TS saves budget. It eliminates ambiguity and reduces rework risk. Using a detailed TS reduces development time by up to 2 times compared to ad-hoc requirements.
Characteristics of a Quality TS
A good TS includes:
- measurable criteria (LCP < 2.5 s, conversion > 3%),
- unambiguous wording — any developer understands it the same way,
- behavior description, not interface,
- stored in Git with versioning and discussion via Pull Request.
A poor TS is a collection of screenshots and phrases like 'make it beautiful'. It guarantees rework, which costs 3–5 times more.
Why Git is Better for Storing a TS
Markdown + Git offers advantages over Word:
Word vs Git Comparison
| Criterion | Word | Git (Markdown) |
|---|---|---|
| Versioning | Manual (v1, v2) | Automatic (commits) |
| Collaboration | Merge conflicts | Merge without issues |
| Discussion | Inline comments | Pull Request with history |
| Markup | Visual | Text-based, readable in any editor |
A TS in Git is 10 times more convenient for version management. That's our approach.
Components of an E-commerce TS
Purpose and System Goals
Describes the context: who it's for, what business problem it solves, success criteria (conversion >= 3%, load time under 2 seconds).
User Roles and Permissions
Example access matrix:
| Action | Guest | Customer | Manager | Admin |
|---|---|---|---|---|
| Browse catalog | ✓ | ✓ | ✓ | ✓ |
| Add to cart | ✓ | ✓ | — | — |
| Place order | ✗ | ✓ | — | — |
| Manage orders | ✗ | own | all | all |
| Manage products | ✗ | ✗ | ✓ | ✓ |
| Manage users | ✗ | ✗ | ✗ | ✓ |
Functional Requirements
Each requirement in the format: ID, description, preconditions, result, exceptions. FR-001: User registration
- Preconditions: user not authenticated, email not registered.
- Scenario: enter email, password, name; validation; create account with status 'not confirmed'; send email with link (TTL 24 hours).
- Exceptions: email already in use → error; invalid email → error; send failure → retry queue.
- Result: record in users table, record in email queue.
Non-functional Requirements
- Performance: 95th percentile API < 300 ms at 100 rps; FCP < 1.5 s, LCP < 2.5 s; JS bundle < 150 KB gzipped.
- Reliability: uptime 99.5%, recovery < 15 minutes, daily backups with 30-day retention.
- Security: JWT (TTL 1 hour + refresh 30 days), bcrypt (cost 12), rate limiting, HTTPS, HSTS, parameterized queries, CSP.
Integrations
- Payment: YooKassa (API v3: card, SBP, YooMoney), webhook with HMAC-SHA256.
- Shipping: CDEK (calculation, waybill creation, tracking).
- Email: SendGrid (transactional: confirmation, recovery, status updates).
- Analytics: Yandex.Metrica + GA4 with e-commerce.
Data Schema
users (1) --- (N) orders orders (1) --- (N) order_items order_items (N) --- (1) products products (N) --- (1) categories products (1) --- (N) product_images users (1) --- (1) carts carts (1) --- (N) cart_items Environments and Deployment
- development: Docker Compose locally
- staging: staging server for pre-release testing
- production: live server
- CI/CD: develop → auto-deploy to staging, main → manual deploy to production with mandatory test run
- Monitoring: UptimeRobot (every minute), Sentry (errors), Grafana + Prometheus (metrics)
Acceptance Criteria
- Pagination (20 products per page)
- Filtering by category, price, availability
- Sorting by price, novelty, popularity
- Full-text search from 3 characters
- Product card: photo, description, price, 'Add to cart' button
- Breadcrumbs with BreadcrumbList microdata
- LCP < 2.5 s on mobile (Lighthouse)
- Adding a non-existent product returns 404
Timeline for TS Preparation
For a medium-sized e-commerce site (50–100 screens), drafting a TS takes 2–3 weeks. This includes analytical interviews, scenario writing, non-functional requirements, and technical review. The cost is calculated individually — depends on complexity and number of integrations.
Typical Mistakes When Drafting a TS
- Describing the interface instead of behavior
- Skipping non-functional requirements
- Using vague phrases without numbers
- Not specifying exceptions and edge cases
- Storing the TS in Word without versioning
What's Included in the Work
- Full audit of the current state (if a prototype or previous documentation exists)
- Interviews with key client employees (up to 5 people)
- Formation of functional and non-functional requirements
- Description of integrations and data schema
- Creation of role and permission matrix
- Agreement and recording of acceptance criteria
- Versioning in Git with change history
- Final review with the development team
We guarantee transparency at every stage. Order a technical specification — we start with an audit. Get a consultation for your project.