Creating Technical Specifications for Website Development
A technical specification is a document that fixes what exactly will be developed, in what form, and how it will be verified. Poor TSpec is a source of disputes about who's right. Good TSpec is a communication tool between the customer, developers, and testers.
The main mistake in writing TSpec: describing the interface instead of behavior. "A blue button in the right corner" is not TSpec. "When the 'Place Order' button is clicked, the system creates an order with draft status, reserves the item from inventory, sends a confirmation email, and redirects the user to /orders/{id}" is TSpec.
Technical Specification Structure
1. System Purpose and Goals
Describes the context: who it's created for, what business problem it solves, what success criteria are (not "convenient website" but "conversion to inquiry not less than 3%", "homepage load time up to 2 seconds").
2. User Roles and Permissions
Roles:
- Guest (unauthenticated user)
- Customer (registered user)
- Manager (company employee)
- Administrator
Access matrix:
| Action | Guest | Customer | Manager | Admin |
|---------------------|-------|----------|---------|-------|
| View catalog | ✓ | ✓ | ✓ | ✓ |
| Add to cart | ✓ | ✓ | — | — |
| Place order | ✗ | ✓ | — | — |
| Manage orders | ✗ | own | all | all |
| Manage products | ✗ | ✗ | ✓ | ✓ |
| Manage users | ✗ | ✗ | ✗ | ✓ |
3. Functional Requirements
Each requirement in format: identifier, description, preconditions, result, exceptions.
FR-001: User Registration
Preconditions:
- User is not authenticated
- Email is not registered in the system
Main scenario:
1. User enters email, password, name
2. System validates data (email format, password ≥ 8 characters)
3. System creates account with "unverified" status
4. System sends confirmation email with link (TTL 24 hours)
5. User receives "Check email" message
Exceptions:
- Email already in use → error "This email is already registered"
- Invalid email → validation error
- Email send error → task is queued for retry,
user sees "Email will arrive shortly"
Result: record in users table, record in email queue
4. Non-Functional Requirements
Performance:
- API response time: 95th percentile < 300ms at 100 rps load
- Catalog page: FCP < 1.5s, LCP < 2.5s (Core Web Vitals)
- Initial JS bundle size: < 150KB gzip
Reliability:
- Uptime: 99.5% (scheduled downtime outside business hours)
- Time to recover from failure: < 15 minutes
- Database backup: daily, stored 30 days
Security:
- Authentication: JWT with 1 hour TTL + refresh token 30 days
- Password hashing: bcrypt, cost factor 12
- Rate limiting: 5 failed login attempts → block for 15 minutes
- HTTPS everywhere, HSTS header
- SQL injections: only parameterized queries, ORM
- XSS: Content Security Policy, sanitize user input
5. Integrations
External services:
- Payment: YooKassa (API v3)
- Methods: bank card, SBP, YooMoney
- Webhook: POST /api/payments/webhook (HMAC-SHA256 signature)
- Delivery: CDEK API v2
- Calculate cost during order placement
- Create waybill on order confirmation
- Track via webhook or polling (every 4 hours)
- Email: SendGrid (transactional)
- Registration confirmation
- Password recovery
- Order status
- Analytics: Yandex.Metrica + GA4
- eCommerce (product view, add to cart, purchase)
6. Data Schema
Not full ERD diagram, but key entities and relationships:
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
7. Environments and Deployment
Environments:
- development: locally (Docker Compose)
- staging: https://staging.example.com — for pre-release testing
- production: https://example.com
CI/CD:
- Branch develop → auto-deploy to staging
- Branch main → deploy to production (manual confirmation)
- Test run required before deploy
Monitoring:
- Uptime: UptimeRobot (check every minute)
- Errors: Sentry
- Metrics: Grafana + Prometheus
8. Acceptance Criteria
Clear conditions for work completion:
Module "Catalog":
☐ Product list with pagination (20 products per page)
☐ Filtering by category, price, availability
☐ Sorting by price, newness, popularity
☐ Search works (full-text, from 3 characters)
☐ Product card: photo, description, price, "Add to cart" button
☐ Breadcrumbs with BreadcrumbList micromarkup
☐ Product card LCP < 2.5s on mobile (Lighthouse)
☐ Test: adding non-existent product returns 404
Document Format
TSpec lives in Git with the code. Markdown + PlantUML for diagrams. Versioned, reviewed via PR. Requirement changes go through PR with discussion, not Telegram.
Reasonable volume for TSpec: 30–80 pages for medium complexity website. Less — insufficient detail. More — TSpec for TSpec's sake that nobody reads.
Timeline
Creating TSpec for medium e-shop (50–100 screens) — two to three weeks including iterations with customer. This includes: analytical interviews with stakeholders, writing use scenarios, agreeing non-functional requirements, technical team review. Savings on TSpec usually result in rework costing 3–5 times more.