Not sure which lesson to do first? Find your level and get a plan →

CS Thinking · Software Design & Development · Grade 9-12

Design Specification

A document that describes what a software system should do, how it should behave, and what constraints it must satisfy, before coding begins.


Quick Answer

A document that describes what a software system should do, how it should behave, and what constraints it must satisfy, before coding begins. Write one whenever more than one person must agree on what is being built, such as a client and a developer, or a team splitting the work. It lists functional requirements (what the system does), non-functional requirements (how fast, how secure, on which devices) and acceptance criteria that turn each requirement into a pass/fail test. It describes behaviour, not the code that will produce it.

Why This Matters

A spec is what lets a team say 'done' and prove it. 'Search results appear within 1 second for 10,000 books' can be tested; 'search should be fast' can only be argued about. Without a spec, a team discovers missing needs after coding, when a change means rework instead of editing a sentence, and the client and developer can each be right about two different products.

Intuitive Explanation

Suppose the school library asks for an app. 'Students can find books' is a wish. A spec turns it into statements someone can check: a student can search by title, author or ISBN; results show whether each copy is on the shelf or on loan; a search returns results within 1 second for a catalogue of 10,000 books; the app works on a phone screen 360 pixels wide; no student can see who borrowed a book. The first two are functional requirements, things the system does. The other three are non-functional: how well, on what, and under which limits.

Each requirement then gets an acceptance criterion, a test that passes or fails: load 10,000 books, search for 'Orwell', and at least one result must appear in under 1 second. If you cannot write such a test, the requirement is still too vague. Specs are written with the client and real users, because developers working alone tend to specify what is easy to build rather than what is needed.

A spec says what, not how. 'Store the catalogue in a PostgreSQL database' or 'loop through the books comparing titles' are design and implementation decisions; they belong in pseudocode, flowcharts or a technical design. To sort a sentence, ask whether two teams could write completely different code and both satisfy it. If yes, it belongs in the spec; if the sentence already picks the tool or the algorithm, it does not.

Think of it like this. A design spec is the order you give a custom cake baker: serves 20, chocolate, no nuts, ready by 3 pm, blue lettering. It says what you will accept and how you will check, and leaves the recipe to the baker. Software specs differ in one way: requirements often shift mid-project, so the spec gets revised rather than framed.

Core idea. Good specifications reduce wasted effort. Building the wrong thing is more expensive than spending time on a clear spec.


When to Use

Write or analyse a spec when a task asks what a system must do, what constraints it has (speed, security, devices, users), or how you will know the result is acceptable before it is built. Words like requirement, client brief, user needs or 'the app should' point here. If the question asks for the steps of one algorithm, use pseudocode or a flowchart; if it asks about the order of phases across a whole project, use the Software Development Life Cycle.

Tip. Ask: Does the task ask what the finished software must do and how each requirement will be checked, before any code exists?

How to Recognize It

Check whether the document states outcomes the software must meet, or instead describes steps, existing code or the project schedule.

  1. Does each line say what the software must achieve, such as 'saves a draft every 30 seconds'?

    Yes means a design specification. Lines that describe how to compute something, step by step, are Pseudocode.

  2. Can each requirement be checked with a pass/fail test, such as 'search results appear within 2 seconds'?

    Yes means it is a usable requirement with an acceptance criterion. 'The app should be fast' fails this check and needs a number.

  3. Does the document describe a program that already exists, so that people can use or change it?

    Yes means it is Documentation, written during or after building. A specification is written before, about what is to be built.

  4. Is the question about when requirements are gathered and what happens to them next?

    Yes means it is about the Software Development Life Cycle; the specification is the output of its requirements phase, not the whole process.

Design Specification vs Pseudocode vs Documentation vs Unit Testing

All four are written around the same software, and each can mention inputs, outputs and expected results. Ask when it is written and what it describes: required behavior before coding, the steps of a method, the finished system, or code that checks one function.

Design Specification

Meaning
A design specification states what the software must do and within what limits, so builders and clients agree before coding.
Key test
Written before building; each line is a checkable requirement, not a step.
Example
'Users can reset a password by email, and the link expires after 1 hour' is one requirement with its own test.

Pseudocode

Meaning
Pseudocode describes, in structured plain language, the steps one algorithm follows to produce its result.
Key test
Gives the how of one task, line by line.
Example
IF email IS registered THEN SEND reset link ELSE SHOW 'No account found'.

Documentation

Meaning
Documentation explains a system that already exists, such as how to install it, use it or change its code.
Key test
Written during or after building, about what the software actually does.
Example
A README section saying 'Run python app.py, then open the address it prints in a browser'.

Unit Testing

Meaning
Unit testing is code that runs one function with known inputs and checks its output automatically.
Key test
Runnable code that passes or fails, one function at a time.
Example
assert is_valid_email('a@b.com') == True checks one small rule taken from the specification.

Formula & Notation

Worked Examples

Example 1 — Turn a client's wish into a spec

Easy

A café owner says: 'I want customers to order coffee from their phones, and it shouldn't be slow or crash at lunchtime.' Write a short design spec with two functional requirements, two non-functional requirements and one acceptance criterion.
Show the steps and the answer
  1. Pull out what the system does. F1: a customer can choose a drink, size and milk and sees the price before paying. F2: the customer gets an order number and a notification when the drink is ready.

    Functional requirements are actions the user takes or the system performs; 'order coffee from their phones' hides these two.

  2. Turn 'slow' and 'crash' into numbers. N1: the order page loads in under 2 seconds on a 4G phone. N2: the system handles 200 orders between 12:00 and 13:00 without failing.

    Those words are the owner's real worries; numbers make them testable and give the developer a target.

  3. Write an acceptance test for N2: simulate 200 orders in one hour; all 200 receive order numbers and none returns an error.

    An acceptance criterion is an experiment the client can watch, so 'finished' is not a matter of opinion.

  4. Read the spec for technology names; there are none.

    The developer is still free to build a website or a phone app, which is a design decision, not a requirement.

Answer: F1: choose drink, size and milk and see the price. F2: get an order number and a ready notification. N1: page loads in under 2 s on 4G. N2: 200 lunchtime orders in an hour with no failures. Acceptance: a simulated 200-order hour completes with zero errors.

Takeaway: Split a brief into what the system does and how well it must do it, then attach a number and a test to every 'how well'.

Example 2 — Spec line or implementation choice?

Standard

A team's spec for a homework tracker has three lines: (a) 'Students can mark a task as done and see it move to a Completed list.' (b) 'Use a JavaScript array sorted with bubble sort to order tasks by due date.' (c) 'Tasks are shown in due-date order, and a list of 500 tasks displays in under 1 second.' Which lines belong in the design specification?
Show the steps and the answer
  1. Test line (a): could two teams write different code and both satisfy it? Yes.

    It describes behaviour the user sees, a functional requirement, so it belongs.

  2. Test line (b): it names a data structure and a sorting algorithm.

    That is how the code works, not what the user gets. Bubble sort is also slow on big lists, a choice the developer should be free to change. It belongs in the technical design.

  3. Test line (c): it states the order users see and a measurable time limit.

    It captures the need behind (b), sorted tasks shown quickly, without choosing the method, so it is the spec's version of that idea.

Answer: Lines (a) and (c) belong in the spec; line (b) is an implementation decision for the design or code plan.

Takeaway: When a spec line names a tool or algorithm, rewrite it as the result the user needs plus a measurable limit.

Example 3 — Find the mistake: a requirement nobody can test

Application

Kai's spec for a school login page says: 'The login should be secure and easy to use.' His teacher marks it as untestable. Find the mistake and rewrite it as testable requirements.
Show the steps and the answer
  1. Try to write a pass/fail test for 'secure'.

    No tester can pass or fail a page on 'secure', because the word sets no threshold.

  2. Replace 'secure' with checkable rules: after 5 wrong passwords in a row the account locks for 15 minutes; passwords must be at least 12 characters; the password is never shown as plain text.

    Each rule is a specific behaviour a tester can try and observe.

  3. Replace 'easy to use' with a measured target: in a test with 10 students who have never seen the page, at least 9 log in within 30 seconds without help.

    Ease of use becomes measurable once you name the users, the task, the time limit and the success rate.

Answer: Lock the account for 15 minutes after 5 wrong passwords; require passwords of 12 or more characters; never display the password; at least 9 of 10 first-time students log in within 30 seconds without help.

Takeaway: Secure, fast and easy are goals; the spec needs the behaviour or number that shows each goal is met.

Where You'll See It

  • An architect's blueprint

    Before building a house you draw exactly what rooms, sizes, and code requirements it needs; a design spec is the blueprint for software — what it must do and how to verify it — written before any code.

  • Ordering a custom birthday cake

    Telling the baker 'chocolate, serves 20, no nuts, ready by 3pm' is a clear spec with measurable, testable requirements; saying just 'make it nice' leads to the wrong cake.

  • Rules for a class group project

    Agreeing up front on what the project must include and how it'll be graded (acceptance criteria) prevents the team from building the wrong thing and arguing later.

Common Mistakes

  1. The slip: A requirement like 'the system should be fast' is specific enough.

    Why it's tempting: Everyone agrees fast is good, so it sounds like a clear goal.

    Instead: Requirements must be measurable and testable, e.g. 'pages load in under 2 seconds', so you can actually verify whether they're met.

  2. The slip: A spec should say which database and framework to use.

    Why it's tempting: Those feel like important decisions, so putting them in the spec seems thorough.

    Instead: A spec focuses on what and why (requirements, behavior, constraints), leaving the how (specific tech) to the design/implementation stage.

  3. The slip: The developers can write the whole spec on their own.

    Why it's tempting: They're the experts who'll build it, so they seem best placed to define it.

    Instead: Specs must involve end users and stakeholders; without their input the spec misses real needs and the right-built software still solves the wrong problem.


Mini Practice

Try these on your own. Tap Reveal when you want to check.

  1. Rewrite these two requirements so they can be measured: 'The app should be fast' and 'The app should handle lots of users.'

    Hint: Add numbers someone could test, such as a time, a count or a percentage.

  2. Classify each requirement as functional or non-functional: (a) users can reset a password by email; (b) pages load in under 2 seconds; (c) reports can be exported as PDF; (d) passwords are stored encrypted.

    Hint: Functional says what the system does; non-functional says how well or how safely.

  3. Write two acceptance criteria for the requirement 'A student can submit homework before the deadline.'

    Hint: Describe a situation, an action, and an exact result you can check.

  4. Spec: 'Login locks the account for 10 minutes after 3 wrong passwords in a row.' Test log: the system allowed a 4th wrong attempt, then locked the account for 10 minutes. Pass or fail?

    Hint: Compare the log with the spec one detail at a time.

  5. A document contains: 'SET attempts TO 0. WHILE attempts < 3 AND password is wrong: ask again.' Is this a design specification or pseudocode?

    Hint: Does it say what the system must do, or how the steps run?

  6. A spec says: 'The system shall use a MySQL database with a table named users_v2.' Why is this a weak requirement, and how could it be rewritten?

    Hint: Does it describe what users need, or how the code is built?

Want the full set?

50 practice questions for this concept — free to try, every one with a complete worked solution showing the why, not just the answer.

Frequently Asked Questions

Is a design specification the same as a requirements document?

In school courses the two names are often used for the same thing: the list of what the product must do. In industry they are usually separate. A software requirements specification states what the system must do for its users, and a design document, written next, decides how: which screens, which database, how the parts talk to each other. The two are checked against each other, so a design choice that breaks a requirement is caught on paper.

What happens when the client changes their mind halfway through?

The specification gets a new version, and the change is weighed before anyone codes it. Teams usually record who asked for the change, why, and what it affects, because one new requirement, such as 'also work offline', can touch every part of a design. In agile projects this happens all the time, so the specification is kept short and updated every cycle rather than signed once and frozen.

What are user stories?

A user story is a short way of writing a requirement from the user's side, in the form 'As a student, I want to save a half-finished quiz, so that I can finish it later.' Each story names who needs the feature, what they want and why, and it is paired with acceptance criteria that make it testable. Agile teams often keep their whole specification as a list of user stories instead of one long document.

Why do specifications use 'must' and 'should' so carefully?

Because the words set priorities. In many specifications, 'must' marks a requirement the product cannot ship without, 'should' marks one that is wanted but can wait, and 'may' marks an optional extra. A widely used internet standard, RFC 2119, defines these words exactly for that reason. Clear wording stops a team from spending a week on a 'may' while a 'must' is still broken.

Learning Path

Design Specification

You are here

You should know Pseudocode and Flowchart, the tools for planning how an algorithm works. A design specification sits a level above them: it fixes what the whole system must do, how well, and how each requirement will be tested, before anyone chooses algorithms. Next, the Software Development Life Cycle places the spec in the requirements and design phases and shows how it guides coding, testing and maintenance.

See Also