What to Include in a Technical Spec for a Web Project

Most failed web projects don't fail because of bad code. They fail because nobody agreed on what was being built. A technical specification (tech spec) is the document that closes that gap — translating a fuzzy idea into something a developer can actually build, price, and deliver.

If you've ever received a quote that ballooned mid-project, or launched a site that didn't do what you expected, the missing ingredient was almost always a clear spec. Here's exactly what to put in one.

Why a Technical Specification Matters

A good spec does four things at once:

• Forces you to make decisions before code is written (when changes are cheap)
• Gives developers a single source of truth to estimate against
• Defines what "done" looks like, so you can sign off without arguments
• Protects both sides legally if expectations diverge

Without one, you're paying hourly for someone to guess what you want. With one, you're paying for execution against an agreed plan.

The Core Sections Every Web Project Spec Needs

1. Project Overview and Goals

Start with two paragraphs maximum. Answer:

• What is this project? (e.g., "A booking site for a 3-location yoga studio")
• What business outcome should it produce? (e.g., "Reduce phone bookings by 60% within 90 days of launch")
• Who is the primary user? (e.g., "Returning customers booking weekly classes on mobile")

If you can't write this clearly, the rest of the spec will be confused too.

2. Scope: What's In and What's Out

This is the section that prevents 80% of disputes. Split it into two lists.

In scope:

• Homepage, About, Services (3 pages), Contact
• Booking system with Stripe payments
• Email confirmation via Postmark
• Admin dashboard to view/cancel bookings

Out of scope (explicitly):

• Mobile app
• Loyalty points system
• Multi-language support
• Content writing (client provides)

Being explicit about what's not included is more valuable than listing what is.

3. Functional Requirements

Describe what the system does, feature by feature. Use the format: As a [user], I can [action] so that [outcome].

Example for a booking flow:

• As a visitor, I can view available class times for the next 14 days so I know when to book
• As a visitor, I can book up to 4 spots in one transaction so I can bring friends
• As a logged-in user, I can cancel a booking up to 2 hours before start time so I get a refund
• As an admin, I can mark a class as full so no new bookings are accepted

Each line becomes a testable piece of work. Vague requirements like "users can book classes" cause vague (and expensive) implementations.

4. Non-Functional Requirements

These are the qualities the system must have, separate from features:

• Performance: Pages load in under 2 seconds on 4G mobile
• SEO: Lighthouse score above 90 on all public pages
• Accessibility: WCAG 2.1 AA compliance
• Browser support: Latest 2 versions of Chrome, Safari, Firefox, Edge
• Uptime: 99.9% measured monthly
• Security: HTTPS, encrypted password storage, GDPR-compliant cookie banner

5. Technical Stack and Integrations

If you have preferences (or constraints from your existing systems), list them. If you don't, say so and let the developer recommend.

Example:

• Frontend: Next.js (existing team familiarity)
• Hosting: Vercel
• Database: PostgreSQL on Supabase
• Payments: Stripe Checkout
• Email: Postmark transactional
• Analytics: Plausible (no cookie banner required)
• CRM sync: HubSpot via webhook on new booking

6. Content and Data Model

List every type of content the site stores and the fields each one has. For a yoga studio:

Class:
  - title (string)
  - instructor (relation to Instructor)
  - start_time (datetime)
  - duration_minutes (int)
  - max_spots (int)
  - location (relation to Location)
  - price_cents (int)

Booking:
  - user (relation to User)
  - class (relation to Class)
  - status (enum: confirmed, cancelled, attended)
  - created_at (datetime)

This single section often saves a week of back-and-forth during development.

7. User Flows and Wireframes

For each key task, describe the steps. You don't need polished designs — even ASCII or a Figma sketch works. Example:

1. User lands on homepage → clicks "Book a class"
2. Selects location → sees calendar of next 14 days
3. Clicks a class → sees details and "Book" button
4. If not logged in → prompted to log in or check out as guest
5. Stripe Checkout → success page → email confirmation

8. Acceptance Criteria

How will you know each feature is done? Write checklists that someone other than you could verify.

For the booking flow:

• Booking a full class shows an error and doesn't charge the card
• Cancelling within 2 hours shows an error but allows cancellation without refund
• Confirmation email arrives within 60 seconds
• Admin can see the booking in the dashboard within 5 seconds

9. Timeline, Milestones, and Budget

Break the project into phases with deliverables. A typical structure:

1. Discovery & design (week 1–2): wireframes, visual design, approved spec
2. Build phase 1 (week 3–4): public site + content pages
3. Build phase 2 (week 5–6): booking system + payments
4. QA and launch (week 7): testing, fixes, go-live

Tie payment milestones to deliverables, not dates.

10. Change Request Process

State how changes will be handled before they happen. Example: "Any work outside the in-scope list requires a written change request, an updated estimate, and written approval before work begins."

A Lightweight Template You Can Steal

If you want a starting point, copy this outline into a Google Doc:

1. Overview & goals (1 paragraph)
2. Target users (3 personas max)
3. In scope / Out of scope
4. Functional requirements (user stories)
5. Non-functional requirements
6. Tech stack & integrations
7. Data model
8. User flows
9. Acceptance criteria per feature
10. Timeline & milestones
11. Change process

Keep it to 8–15 pages. Anything longer rarely gets read; anything shorter usually leaves gaps.

Common Mistakes That Make Specs Useless

• Writing it after design starts. The spec should drive design, not document it retroactively.
• Using vague verbs. "Manage," "handle," and "support" mean nothing. Use "create, edit, delete, list, filter."
• Skipping the data model. Without it, every developer will invent a different one.
• Treating it as a contract instead of a tool. Specs should evolve — version them, date them, and update them when scope changes.
• Doing it alone. Run the draft past the developer who'll build it. They'll catch contradictions you missed.

When to Get Help Writing One

If you've never written a tech spec before, the first one will take longer than the project itself feels worth. That's normal. You can either invest a few days learning, or work with an agency that runs a structured discovery process and produces the spec for you as part of the engagement.

At Axoxweb, every project starts with a discovery sprint that produces exactly this document — so you own a spec you can take to any developer, even if you don't continue with us. If you'd rather skip the guesswork and start your next web project with a solid plan, get in touch at axoxweb.com.