How to Write a Technical Specification in English
Structure and language for technical specifications: functional vs non-functional requirements, 'shall' vs 'should', spec document sections, and writing with precision.
A technical specification (or tech spec) is a document that describes what a system should do, how it should behave, and the constraints it must operate within. Writing a clear specification in English — especially one that distinguishes mandatory requirements from optional ones — is one of the most valuable skills for senior engineers and technical leads.
This guide covers the structure, vocabulary, and key linguistic conventions of technical specifications.
Why Precision Matters in Specs
Ambiguous specifications cause expensive mistakes. If a spec says “the system should be fast,” the developer and the product manager may have completely different interpretations. If it says “the API must respond within 200 ms at the 95th percentile under a load of 1,000 concurrent users,” there is no ambiguity.
Good specification language is:
- Unambiguous — only one interpretation is possible
- Testable — you can write a test that verifies the requirement
- Complete — it specifies the behaviour under all relevant conditions
”Shall” vs “Should” vs “May”
The most important linguistic convention in technical specifications is the distinction between shall, should, and may. This convention comes from RFC 2119, a widely-used standard in software engineering.
”Shall” / “Must” — Mandatory Requirements
“Shall” (or “must”) indicates an absolute requirement. The system must implement this, no exceptions.
“The authentication endpoint shall validate the JWT signature before processing any request.” “The system must not store user passwords in plaintext.” “All API responses shall include a
Content-Typeheader."
"Should” — Recommended Requirements
“Should” indicates a recommendation. There may be valid reasons to deviate, but the default expectation is compliance.
“Error responses should include a human-readable message alongside the error code.” “Log entries should include a correlation ID to support distributed tracing.” “The system should handle requests within 200 ms under normal load conditions."
"May” — Optional Features
“May” indicates a feature that is permitted but not required.
“The API may accept both JSON and XML request bodies.” “Clients may cache responses for up to 60 seconds using the
Cache-Controlheader.”
Functional vs Non-Functional Requirements
Functional Requirements
Functional requirements describe what the system does — the behaviours, features, and functions it provides.
“The system shall allow registered users to reset their password via a link sent to their registered email address.” “The API shall return a 404 status code when a requested resource does not exist.” “The notification service shall send a push notification to the user’s device within 30 seconds of a trigger event.”
Non-Functional Requirements
Non-functional requirements (NFRs) describe how the system behaves — its quality attributes such as performance, availability, security, and scalability.
Common categories of NFRs:
- Performance: “The search API shall return results within 500 ms at the 99th percentile.”
- Availability: “The service shall maintain 99.9% uptime, measured monthly.”
- Scalability: “The system shall support at least 10,000 concurrent users without degradation.”
- Security: “All data in transit shall be encrypted using TLS 1.2 or later.”
- Maintainability: “The codebase should achieve at least 80% test coverage.”
“Non-functional requirements are often neglected in early specs but are critical for system design. A functional requirement tells you what to build; a non-functional requirement tells you the constraints within which you must build it.”
Spec Document Structure
Standard Sections
A typical technical specification includes these sections:
1. Overview / Purpose
“This document specifies the behaviour of the User Authentication Service (UAS). It is intended for the backend engineering team, the security team, and the QA team.”
2. Scope
“This specification covers the registration, login, session management, and password reset flows. It does not cover social login or two-factor authentication, which will be addressed in a separate specification.”
3. Definitions and Acronyms
“For the purposes of this document: ‘session’ refers to a server-side session identified by a session token stored in an HttpOnly cookie.”
4. Functional Requirements Numbered requirements using “shall”:
“UAS-FR-001: The system shall accept a username and password for authentication.” “UAS-FR-002: The system shall reject authentication requests where the password does not match the stored hash.”
5. Non-Functional Requirements
“UAS-NFR-001: The login endpoint shall respond within 300 ms at the 95th percentile.” “UAS-NFR-002: Failed login attempts shall be rate-limited to five per minute per IP address.”
6. Error Handling
“When authentication fails, the system shall return HTTP 401 with an error code of
INVALID_CREDENTIALS. The response body should not indicate whether the username or the password was incorrect.”
7. Open Questions
“The session expiry duration has not been finalised. Options under consideration: 24 hours (default), 7 days (remember me option). Decision required by 2026-06-21.”
Useful Language for Specifications
Conditions and Constraints
“Under no circumstances shall the system…” “In the event that [X], the system shall…” “Where [condition], the behaviour shall be…” “Except where otherwise specified…”
Referencing Other Requirements
“This requirement supersedes UAS-FR-002.” “This requirement is conditional on UAS-FR-005 being satisfied.” “See Section 4.3 for the related security requirements.”
Noting Ambiguity or Open Questions
“TBD: The exact format of the error response body is to be determined.” “Note: This behaviour may need to be revisited if the third-party provider changes their API.” “Open question: Should the session be invalidated on password change, or only on explicit logout?”
Common Mistakes in Spec Writing
Vague language: “The system should be user-friendly.” — Untestable. Replace with specific criteria.
Mixing requirements and design: “The system shall use Redis to store session data.” — This is a design decision, not a requirement. Write: “Session state shall be stored in a cache with a read latency below 5 ms.”
Missing negative requirements: Specs often say what the system must do, but omit what it must not do. Add explicit negative requirements for security and data handling.
“The system must not log request bodies containing authentication credentials.” “The API shall not expose internal error messages or stack traces in responses to clients.”
Writing a precise technical specification takes practice, but the linguistic conventions are learnable. Once you understand the difference between “shall”, “should”, and “may”, and between functional and non-functional requirements, you have the foundation for writing specifications that engineering teams can actually build to.