STACKS AND SPRINTS · VOLUME 1 OF 2 · 208 TERMS

Builds and branches

Words for judging software, and for how it is built, versioned, tested, shipped, connected and secured.

Much of what sounds like engineering jargon is a way of saying how sure, how bad or how reversible something is. Twenty-three words for judging software, 453 for the things behind the screen, and 22 that mean something else to engineers.

Instruments and Moves names what happens in the words. Marks and Measures names what happens on the page. This one names what happens behind the screen: how software is built, shipped, broken and fixed. It’s written for educators, policy staff, designers and anyone else who commissions, funds or depends on software without writing it.

STACKS AND SPRINTS IN TWO VOLUMES

Read in order, or open the volume you need

VOL 1 Builds and Branches · A1–A5 · B1–B6 · this volume Words for judging software, and for how it is built, versioned, tested, shipped, connected and secured
VOL 2 Runbooks and Roadmaps · B7–B14 · C1–C2 How software is run, fixed, planned and delivered, the patterns behind it, and the words that mean something else to engineers
INDEX The phrasebooks glossary · every term in the four toolkits, A to Z, with the volume that holds it

Stacks and Sprints runs to two volumes so that each stays short enough to read in one sitting. Every volume holds whole sections in the toolkit’s own order, with the appendices for its own entries. The toolkit closes with the three questions, asked in the team’s own words, at the end of volume two.

The phrasebooks glossary lists every term in all four toolkits and opens it in the volume that holds it.

WHY THE VOCABULARY IS WORTH LEARNING

How bad is it? How sure are we? Can we undo it?

A large share of these terms calibrate risk. Severity and priority, staging and production, canary releases, rollbacks, feature flags and “four nines” all answer one of those three questions.

They do the same job as the hedges and qualifiers in Instruments and Moves. A non-engineer who knows them can ask those three questions in words the team already uses, and get an answer that can be checked rather than a reassurance that can’t.

The rest of the vocabulary names the things the questions are about: the parts of the stack, the stages of delivery, the people who decide. Knowing which word belongs to which question is most of what a commissioning team needs.

THREE QUESTIONS

Each question has its own words

Ask how bad it is, and the answer comes in severities and blast radius. Ask how sure, and it comes in environments and tests. Ask whether it can be undone, and it comes in flags and rollbacks.

FIG 01 — SEVEN WORDS THAT ANSWER EACH QUESTION, WITH THEIR FAMILIES

The dot beside each word is its kind. Most of the answers are measures, stages and statuses: things that can be looked up, not opinions. That is the point of the vocabulary. “It should be fine” is an opinion. “It passed UAT on staging and it’s behind a flag” is three facts.

The close returns to these questions with the words to ask them in.

THE THIRD IN THE SET

In the words, on the page, behind the screen

Instruments and Moves names what happens in the words. Marks and Measures names what happens on the page. This one names what happens behind the screen, and keeps the same shape.

FIG 02 — THREE TOOLKITS, ONE SHAPE

Words for judging play the part of the instruments: qualities that tell you what to look for. Words for things play the part of the moves: what you see named. Defects play the part of the vices.

The new part is the third. Software vocabulary borrows heavily from ordinary words, and many of those words are already in daily use in education and policy with a different meaning. Part three is for the meetings where that difference costs time.

EIGHT KINDS OF WORD

Every term is one of eight kinds.

Most are parts: components, files and tools. Forty-eight are defects, named faults that play the part of the vices in Instruments and Moves.

FIG 03 — THE TERMS IN PART TWO, BY KIND

Part: a component, file or tool. Measure: a number, threshold or unit. Stage: a step, environment or ritual in delivery. Status: the state a piece of work is in. Role: a job or team. Pattern: a named approach or observation teams reuse. Defect: a named fault or bad pattern. Shorthand: an acronym or slang term used in conversation.

The kind is printed beside every term, in the same colour everywhere, so a reader scanning a plate can find the defects at a glance. The counts are generated from the entries, not typed.

THE SHAPE OF THE COLLECTION

Where the words cluster

Patterns and strategies hold the most terms, then data and AI. The defects gather in bugs, then in the anti-patterns, security and AI.

FIG 04 — TERMS PER FAMILY, BY KIND

The families run from what software is made of to how teams talk about it. The stack, code and data, and version control are the material. Building and shipping, the web, security and operations are the life of a system. Bugs, delivery and roles are the work around it. Data and AI, shorthand and patterns are the vocabulary that travels furthest, and enterprise software is where it meets procurement.

Roles and shorthand are each a single kind, which is why their bars are one colour.

WORDS WITH TWO MEANINGS

Eleven definitions say “two meanings”

ACROSS THE DESK

Another meaning in education and policy

Framework (B1)
Module (B2)
Migration (B2)
Pipeline (B4)
Environment (B4)
Production (B4)

INSIDE ENGINEERING

Two meanings within the trade

Dependency (B2): also a task that waits on another (B9)
Spike (B9): in newsrooms, to kill a story
Dependency (B9): also outside code a project uses (B2)
Product manager (B10): PM also means project manager
Token (B11): also a credential that grants access (B6)

Some words change meaning depending on who is speaking. The ones on the left also have an everyday meaning in schools and ministries, and Part three sets the two side by side. The ones on the right carry two meanings even among engineers. When one comes up, ask which is meant before arguing about the answer.

HOW TO READ A PLATE

Terms, a drawing and where you’ll meet them

01 The heading says what the terms on the plate have in common, or how to tell them apart
02 Each term carries its definition and its kind, in the same colour everywhere
03 The drawing shows the terms as an engineer would see them: boxes, panes, boards and branches
04 The panel says where you’ll meet each term, and how to keep them apart
05 The longform adds the full row from the glossary for every term

Part one works differently. Each judging word has its own slide: the definition, the line it usually arrives as in a review, and a drawing of the system as found and as mended. Part three sets each word’s two meanings side by side.

Where a term shares its name with a field-guide entry, its definition ends with See also and the guide’s name: this glossary defines, the guide analyses. Where the field guides explain why a family’s terms matter, its introduction ends with In the field guides, naming the entries to read.

WHAT THIS COMPANION IS NOT

Three misreadings, refused in advance

01 Not a course in programming. The words are for working with engineers, not for becoming one.
02 Not a buyer’s guide. Products are named only where the product has become the word, such as Git or Docker.
03 Not a licence to overrule. Knowing what a canary release is lets you ask whether there is one. Whether there should be is still the team’s call.

The third misreading is the costly one. A newcomer who has just learnt “technical debt” tends to find it everywhere and to treat it as a verdict on the team. The words here are for better questions: how bad, how sure, and can we undo it.

Part one of three

Words for judging

Twenty-three quality words engineers use in review, in five groups. Like the instruments, they tell you what to look for.

ONE Words for judging
TWO Words for things
THREE Where non-engineers get lost

These are the qualities engineers argue about in design reviews and code reviews. Most of them trade off against each other. Faster can mean less maintainable, and more secure can mean less usable. A good review names the trade-off it is making.

Each entry gives the definition and the line it usually arrives as in a review, then how to see the quality for yourself, how it goes wrong and how to fix it. Every drawing is a pair: the system as found and as mended.

In the field guides.

SPEED AND SCALE

Part one of three

How fast it is, and how far it stretches

Four words for how quickly the software does its work and how it copes when the work grows.

Performance is the overall verdict. Latency and throughput are the two numbers underneath it: how long one request waits, and how many requests the system can take at once. Scalability asks whether those numbers hold as the users multiply.

The distinction between latency and throughput is the one worth keeping. A system can answer one teacher in a blink and still fall over when every teacher in the country logs in at 8 a.m. on results day. That is a throughput problem, not a latency one, and the fixes differ.

A1/SPEED AND SCALE JUDGING

Performance

In a review

FIG 05 — FAST WITH FIVE STUDENTS, SLOW WITH FIFTY

How to see it. Time the slowest thing a real user does, with real data: the class of forty, not the test class of five. Performance problems hide in demo data, because demo data is small.

How it goes wrong. Fast in the demo and slow in the classroom. The usual cause is a page that fetches every record when it shows twenty, or asks the database once per student instead of once per class. The cost grows with the data, so nobody sees it until the data is real.

How to fix it. Measure before tuning. Find the one slow step with real data, fix it and measure again. Agree a target for the actions users repeat most, such as opening a class list, and test against it before each release.

Related · Latency · Throughput · Load test · Premature optimisation

A1/SPEED AND SCALE JUDGING

Latency

In a review

FIG 06 — WHERE TWO SECONDS GO

How to see it. Count the wait between a click and the screen changing, and ask for the slow end, not the average. An average of half a second can hide one click in twenty that takes five, and that is the one users remember.

How it goes wrong. Every click makes a long round trip: to a server on another continent, through several services in turn, to a database that does the same work every time. Each step adds a little and the waits add up.

How to fix it. Shorten the trip or skip it. Serve from nearer the user through a CDN, cache what does not change, run slow work in the background and show progress at once.

Related · Performance · CDN · Cache · Timeout

A1/SPEED AND SCALE JUDGING

Throughput

In a review

FIG 07 — THE SAME PEAK, AGAINST TWO CAPACITIES

How to see it. Ask how many users, submissions or requests the system has handled at once, not how fast it handles one. Then set that against the busiest hour of the year: exam week, results day, the first morning of term.

How it goes wrong. A system sized for an ordinary day meets its peak. Requests queue, waits grow, and then requests start failing outright, usually in the hour that matters most.

How to fix it. Load-test against the real peak before it arrives. Then add capacity or autoscaling, and move slow work into a queue that can catch up after the rush.

Related · Scalability · Load test · Autoscaling · Capacity planning

A1/SPEED AND SCALE JUDGING

Scalability

In a review

FIG 08 — BUILT FOR ONE SCHOOL, THEN FOR ALL OF THEM

How to see it. Ask what has to grow when the users grow: servers, licences, staff time, or nothing at all. A system that scales well grows its costs roughly in step with its users. One that does not hits a wall at some size nobody has tested.

How it goes wrong. One part cannot be multiplied: a single database, a licence charged per server, a manual step somebody performs for every school. The pilot works because the pilot is small.

How to fix it. Find the part that cannot be copied and design around it early, before the pilot becomes the national rollout. Load-test at the size the system will reach, not the size it starts at.

Related · Throughput · Load balancer · Autoscaling · Single point of failure

STAYING UP

Part one of three

Whether it keeps working

Five words for whether the system works when people need it, what happens when part of it fails, and whether anyone can tell.

Reliability and availability describe the record. Resilience and robustness describe the behaviour under strain: a part failing, or input nobody expected. Observability decides whether the team can see any of it happening.

These words are where service contracts live. A vendor that promises availability has promised a number, not a behaviour, and the operations family (B7) holds the words for checking that promise: the nines, the SLA and the error budget.

A2/STAYING UP JUDGING

Reliability

In a review

FIG 09 — A TERM OF FAILURES, BEFORE AND AFTER

How to see it. Look at the record, not the promise: how often it failed last term, and when. Failures that cluster in the busy weeks are a capacity problem wearing a reliability label.

How it goes wrong. The system works in testing and fails in ways nobody planned for: a time-out under load, a full disk, a certificate that quietly expired. Each failure is fixed on the day and none is counted, so the pattern is never seen.

How to fix it. Track every failure as data, fix the commonest cause first, and set a reliability target, an SLO, that the team is measured against.

Related · Availability · SLO · Incident · Postmortem

A2/STAYING UP JUDGING

Availability, uptime

In a review

FIG 10 — THE SAME PERCENTAGE, WITH AND WITHOUT A WINDOW

How to see it. Turn the percentage into time. A promise of 99.9% sounds perfect and still allows almost nine hours of downtime a year; 99% allows more than three and a half days. Then ask when the downtime is allowed to fall.

How it goes wrong. A promise measured over a year and met on average, while the one outage that mattered fell on results day. The contract was kept and the users were let down.

How to fix it. Pair the percentage with a window: school hours, exam periods, results release. Put planned work in a maintenance window outside it, and measure monthly rather than yearly.

Related · The nines · SLA · SLO · Maintenance window

A2/STAYING UP JUDGING

Resilience, fault tolerance

In a review

FIG 11 — ONE SERVICE FAILS. DOES THE REST STAY UP?

How to see it. Pick one part of the system and imagine it gone. Does everything stop, or does the system lose one feature and carry on? The answer is usually in the architecture diagram, where every arrow is a dependency.

How it goes wrong. Everything waits on everything. One slow service makes every page wait for it, the waits pile up and the failure spreads to parts that were working. One missing box takes down the whole picture.

How to fix it. Isolate the parts. Give every call a time-out and a fallback, put a circuit breaker in front of any service that can fail, and remove single points of failure.

Related · Circuit breaker · Graceful degradation · Redundancy, failover · Single point of failure

A2/STAYING UP JUDGING

Robust, brittle

In a review

FIG 12 — ONE REAL NAME, TWO OUTCOMES

How to see it. Feed it what real users will: an apostrophe in a surname, a name in Chinese or Tamil script, a blank field, a file twice the expected size. Brittle software breaks on the first input its author did not imagine.

How it goes wrong. The code assumes its inputs. O’Brien breaks a query, Siobhán becomes Siobh?n, an empty class divides by zero. Each crash is an edge case that was always going to arrive.

How to fix it. Check input at the edge, handle the unexpected case on purpose and say clearly what went wrong. Then add the input that broke it to the tests, so it cannot break the same way twice.

Related · Edge case · Unicode, UTF-8 · Null, undefined · Regression test

A2/STAYING UP JUDGING

Observability

In a review

FIG 13 — GUESSING, AGAINST AN ALERT THAT FIRES FIRST

How to see it. Ask what the team could see during the last incident, and how long it took to find the cause. If the story starts with “users told us”, the system was not observable.

How it goes wrong. Logs nobody can search, no metrics and no alerts. The first sign of trouble is a complaint, and the first hour of the incident is spent guessing which part is broken.

How to fix it. Logs, metrics and traces for the paths that matter, a dashboard of the few numbers that show health, and alerts set to fire before users notice.

Related · Logs, metrics, traces · Monitoring, alerting · Dashboard · MTTR

CHANGE

Part one of three

How easily it can be changed

Six words for whether the code can be read, tested and changed by someone other than its author, later.

Maintainability is the verdict. Readability, testability and complexity are the reasons behind it, and coupling and cohesion describe how the parts are cut. Loose coupling and high cohesion are the goal: each part does one job and leans on the others as little as possible.

This group matters most to people who fund software, because most of a system’s cost arrives after launch. Code that only its author can change is a cost that waits for the author to leave.

A3/CHANGE JUDGING

Maintainability

In a review

FIG 14 — THE SAME CHANGE, BY THE AUTHOR AND BY ANYONE ELSE

How to see it. Ask how long a small change takes, and who can make it. If the answer names one person, the system is less maintainable than it looks, however clean it seems to its author.

How it goes wrong. Clever shortcuts, no comments, no tests and a single engineer who understands it. The code works and nobody dares to touch it, so every change waits for that engineer.

How to fix it. Write for the next reader: plain code, tests, a README, and every change reviewed by someone who did not write it. Measure the time a newcomer takes to ship a small change.

Related · Readability · Testability · Bus factor · Technical debt

A3/CHANGE JUDGING

Readability

In a review

FIG 15 — THE SAME TWO LINES, WRITTEN TO BE READ

How to see it. Read a short piece of the code aloud. If the names say what things are, a non-engineer can follow the gist. If they are single letters and abbreviations, even an engineer has to decode it.

How it goes wrong. Short names, long functions and clever one-liners. The code is quick to write and slow to read, and it will be read far more often than it was written.

How to fix it. Name things for what they are, keep functions short and do one thing at a time. A reviewer’s “I had to read this twice” is a bug report about readability.

Related · Maintainability · Magic number · Code review · Idiomatic

A3/CHANGE JUDGING

Testability

In a review

FIG 16 — ONE FUNCTION, FOUR JOBS, NO TEST

How to see it. Ask whether a piece of the system can be checked on its own, automatically, in seconds. If testing it means sending real emails or changing real records, it is not testable, and in practice it will not be tested.

How it goes wrong. One function that calculates a grade, saves it, emails the parent and writes a report. To test the calculation you have to run all four, so nobody does.

How to fix it. Split the work so that each part does one job and can be checked alone. The calculation becomes a unit test that runs in milliseconds; the email is checked separately.

Related · Unit test · Cohesion · Coupling · Test coverage

A3/CHANGE JUDGING

Complexity

In a review

FIG 17 — SEVEN PARTS FOR A JOB THAT NEEDED THREE

How to see it. Ask how many parts a request passes through, and how many paths there are through the code. Then ask whether the problem really needs that many. Complexity is fine when the problem is complex; the fault is complexity the problem did not ask for.

How it goes wrong. Every part talks to every other part, every feature adds a special case, and nobody can draw the system on one page. Changes take longer and break more.

How to fix it. Remove parts before adding them. Collapse layers that only pass things along, and prefer the simpler design until the problem proves it needs more.

Related · Spaghetti code · Over-engineered · KISS · Big ball of mud

A3/CHANGE JUDGING

Coupling

In a review

FIG 18 — CHANGE ONE TABLE, BREAK THREE MODULES

How to see it. Ask what else has to change when one part changes. In a loosely coupled system the answer is usually nothing. In a tightly coupled one it is a list, and the list is the reason simple changes take weeks.

How it goes wrong. Parts reach into each other’s data and internals. Change the format of one table and three modules that read it directly break at once.

How to fix it. Make parts talk through a defined interface, such as an API, and hide everything behind it. Then each part can change on the inside without the others noticing.

Related · Cohesion · API · Separation of concerns · Breaking change

A3/CHANGE JUDGING

Cohesion

In a review

FIG 19 — SIX UNRELATED THINGS IN ONE FILE

How to see it. Ask what a file or module is for, in one sentence. If the sentence needs “and” three times, cohesion is low. High cohesion means everything in one place serves one purpose.

How it goes wrong. A file called utils or helpers that collects dates, emails, grades, colours and PDF export because each needed a home. Everything depends on it, and every change to it is risky.

How to fix it. Group code by purpose. Move each job to the module it belongs with, so that a change to grading touches the grading code and nothing else.

Related · Coupling · Separation of concerns · Code smell · Maintainability

SAFE AND OPEN

Part one of three

Who it keeps out, and who it lets in

Four words for the system’s boundaries: keeping attackers out, letting every user in, letting other systems talk to it, and letting other engineers build on it.

Security keeps the wrong people out. Accessibility makes sure the right people are not kept out by accident. Interoperability lets other systems in on agreed terms, and developer experience decides whether the engineers on the other side can use those terms without a fight. All four are cheapest when designed in and most expensive when added after launch.

Each has its own vocabulary later in the glossary: security and data protection (B6), the web and learning-technology standards (B5), and shift left (B13), the pattern of moving these checks to the start of the work.

A4/SAFE AND OPEN JUDGING

Security

In a review

FIG 20 — AN ENDPOINT WITH NO ACCESS CHECK

How to see it. For every way into the system, ask two questions: who can reach this, and who should be able to? The gap between the answers is the security problem. Look hardest where student or staff data is returned.

How it goes wrong. An address that returns data without checking who is asking, a secret key pasted into code, a test account with an admin password left on. Each is small; each is how breaches start.

How to fix it. Check identity and permission on every request, keep secrets out of code, give each person and system the least access it needs, and test for weaknesses before launch.

Related · Authentication · Authorisation · Least privilege · VAPT

A4/SAFE AND OPEN JUDGING

Accessibility, a11y

In a review

FIG 21 — IT LOOKS LIKE A BUTTON. IT ISN’T ONE

How to see it. Put the mouse away and try the main task with the keyboard alone, then with a screen reader. If either gets stuck, so will a student or teacher who relies on one.

How it goes wrong. Controls built from plain boxes that look like buttons but are not, images with no text alternative, colour as the only signal. The page looks fine and cannot be used by some of the people it is for.

How to fix it. Use the elements the platform provides, such as a real button, give every image and control a text name, and test with assistive technology before release.

Related · Shift left · Progressive enhancement · Acceptance criteria

A4/SAFE AND OPEN JUDGING

Interoperability

In a review

FIG 22 — BY HAND, AND BY STANDARD

How to see it. List the systems this one must exchange data with, and ask how each exchange happens. A standard, such as LTI or OneRoster, is a good answer. A person downloading and uploading spreadsheets is not.

How it goes wrong. Each tool has its own sign-in and its own class list, kept in step by hand. Data goes stale, mistakes creep in, and teachers end up re-keying marks between systems.

How to fix it. Require the standards in procurement: LTI to launch tools inside the LMS, OneRoster to sync classes from the SIS, QTI to move question banks. Test the exchange, not only the brochure.

Related · LTI · OneRoster · API · Integration · Vendor lock-in

A4/SAFE AND OPEN JUDGING

Developer experience (DX)

In a review

FIG 23 — THREE DAYS TO A FIRST SUCCESS, OR TWENTY MINUTES

How to see it. Ask an engineer outside the team to make one working call to the API, or set up the tool, from the documentation alone, and time it. Twenty minutes to a first success is good developer experience. Three days of guessing at undocumented fields is not.

How it goes wrong. Documentation that is missing or out of date, error messages that say “500” and nothing else, no sandbox to try things in, and every integration needing a call with the vendor. Each partner pays the cost again, and some give up and export spreadsheets instead.

How to fix it. Write the documentation with the API, not after it. Give error messages that say what to fix, working examples and a sandbox. Then measure the time to a first successful call, and treat it as a target in the contract.

Related · API · Sandbox · Interoperability · Integration

READINESS

Part one of three

Whether it is ready, and what it will cost later

Four words for craft and judgement: whether the code is written as its community expects, built for the right problems, fit for real users, and how much it has borrowed against the future.

Idiomatic and over-engineered are judgements about craft. Production-ready is the threshold the work must cross before real users depend on it. Technical debt is the bill for every shortcut taken on the way there.

Technical debt is the most useful of these words outside engineering, because it names a trade every manager makes: speed now, paid for later. The metaphor is Cunningham’s (1992), and it carries the right implication. Debt is not a failure. Unpaid debt is.

A5/READINESS JUDGING

Idiomatic

In a review

FIG 24 — FOUR LINES, OR TWO THE LANGUAGE EXPECTS

How to see it. Ask an engineer who knows the language whether the code reads as that language usually does. Idiomatic code is quicker for the next engineer to read, because it follows patterns they already know.

How it goes wrong. Code written in one language as if it were another: long loops where the language has a one-line form, or a home-made version of something the standard library already does.

How to fix it. Follow the language’s conventions and its style guide, and use a linter to catch the rest. Reviewers flag unidiomatic code because it is harder to maintain, not because it is ugly.

Related · Readability · Linter · Code review · Maintainability

A5/READINESS JUDGING

Over-engineered

In a review

FIG 25 — A PLUGIN SYSTEM FOR TWO FEATURES

How to see it. Ask which part of the design serves a need the users have today, and which serves one somebody imagined. The second kind costs as much to build and maintain as the first.

How it goes wrong. A plugin system for two features, a configuration file for values that never change, three layers of abstraction around one database. Each was added for a future that has not arrived.

How to fix it. Build for the problem in front of you and keep the design easy to change, which is cheaper than predicting the future. YAGNI: you aren’t gonna need it.

Related · YAGNI · Gold plating · Premature optimisation · Complexity

A5/READINESS JUDGING

Production-ready

In a review

FIG 26 — ONE TICK, AND SIX

How to see it. Ask what happens when the demo meets real users: real data, real load, real attackers, a failure at 2 a.m. A production-ready system has an answer for each. A demo has the happy path.

How it goes wrong. The demo works, so the launch date is set. Nobody has tested it under load, nobody is on call, there are no backups and the security testing is booked for after go-live.

How to fix it. Agree the checklist before the demo: tests, monitoring and alerting, security testing, backups, a rollback plan and someone on call. Launch when it is ticked, not when the demo impresses.

Related · Happy path · VAPT · Runbook · Definition of done

A5/READINESS JUDGING

Technical debt

Words for things

453 terms and acronyms in 14 families, from the stack to the slang, the patterns teams reuse and the systems large organisations buy.

ONE Words for judging
TWO Words for things
THREE Where non-engineers get lost

Fourteen families, from the stack to the slang and the systems large organisations buy. Each slide is a plate: a handful of related terms, defined, and one drawing that shows them, so that a word can be matched to the thing it names.

Every term carries one of eight kinds. Acronyms are spelled out in the term itself. Several terms carry two meanings, and their definitions say so. Forty-eight are defects, collected by family in Appendix B.

THE STACK

Part two of three

How software is put together

A product is layers of software, each built on the one below. These words name the layers and where they run.

Thirty-two terms on 11 plates: 30 parts, one status and one defect.

The defect to watch for here: vendor lock-in. Appendix B collects every defect by family.

B1/THE STACK 4 TERMS

The front end is what users touch. The back end is everything else.

Four words for the layers of one product, and for the technologies each layer is built with.

Stack, tech stack

Part

Where you’ll meet it “What’s the stack?”

Front end

Part

Where you’ll meet it “A front-end bug”

Back end

Part

Where you’ll meet it “The back end is timing out”

Full stack

Part

Where you’ll meet it Job titles.

FIG 28 — ONE PRODUCT, ITS TWO ENDS AND ITS TECH STACK

A “front-end bug” lives in what the user sees; a back-end one lives on the servers and often affects everyone at once. When a vendor names its stack, ask whether your team, or the next supplier, can hire for it. A rare stack is a staffing risk long before it is a technical one.

“Full stack” describes a person’s range, not a promise of depth at every layer. A small team of full-stack engineers is common and sensible; it still helps to know who on it owns the database.

B1/THE STACK 4 TERMS

The client asks, the server answers, and the API sets the terms

How one request travels: from a device, through an API endpoint, to the data behind it.

Client, server

Part

Where you’ll meet it Architecture diagrams.

Database

Part

Where you’ll meet it “Is it in the database?”

API (application programming interface)

Part

Where you’ll meet it Integrations between systems.

Endpoint

Part

Where you’ll meet it API documentation.

FIG 29 — A PHONE ASKS ONE ENDPOINT FOR A CLASS LIST

Most integration questions are API questions. Before two systems are called “connected”, ask which endpoints exist, who may call them and what each returns. An endpoint that hands a whole class list to any caller is a privacy question as much as a technical one.

“Is it in the database?” is often the real question behind “is it in the system?”. A figure on screen may be worked out on the fly and never stored, which matters for reports and for requests to see records.

B1/THE STACK 3 TERMS

Your code calls a library. A framework calls your code.

Three kinds of ready-made code, told apart by who is in charge.

Framework

Part

Where you’ll meet it “We’re on a React framework”

Library

Part

Where you’ll meet it Dependencies.

SDK (software development kit)

Part

Where you’ll meet it Vendor integrations.

FIG 30 — WHO CALLS WHOM: FRAMEWORK, LIBRARY, SDK

The difference shows when you change your mind. Swapping a library touches the places that call it; swapping a framework usually means rebuilding the app. An SDK ties the product to the platform it was made for, so ask what happens to the integration if that platform changes its terms.

“Framework” means something else in policy writing; Part three sets the two meanings side by side. In an engineering meeting it almost always means code.

B1/THE STACK 1 TERM

Low-code builds an app from blocks, with little or no code

A way to build software without a software team, by arranging ready-made blocks in a visual tool.

Low-code, no-code

Part

Where you’ll meet it Internal tools and quick prototypes.

FIG 31 — ONE FORM, WRITTEN IN CODE OR BUILT FROM BLOCKS

Low-code tools let a school build a sign-up form or a simple tracker in days rather than months. The limits show later: a need the blocks cannot express, data kept in the platform’s own format, an app nobody maintains once its maker moves on. Ask where the data lives, how it comes out and who owns the app.

A low-code tool is a platform like any other, so the questions about vendor lock-in later in this family apply in full.

B1/THE STACK 3 TERMS

Code is written in a language, run by a runtime, on an OS

What sits under the code: the language it is written in, the program that runs it and the base software of the machine.

Programming language

Part

Where you’ll meet it Hiring and architecture.

Runtime

Part

Where you’ll meet it Version upgrades.

Operating system (OS)

Part

Where you’ll meet it Device support lists.

FIG 32 — THREE LAYERS UNDER EVERY LINE OF CODE

Each layer has its own versions and its own end-of-support dates. When a vendor calls an upgrade “just a runtime change”, it can still break what sits above it. In procurement, ask which versions are supported and for how long, not only whether the product works today.

Device support lists in tenders usually name operating systems. Check them against the devices schools actually have, including older tablets that cannot take the latest version.

B1/THE STACK 2 TERMS

A native app is built per device type, a web app for any browser

Three ways to put a product on a phone, and what each costs to build and keep up.

Native app, web app

Part

Where you’ll meet it Mobile strategy.

PWA (progressive web app)

Part

Where you’ll meet it Mobile strategy.

FIG 33 — TWO BUILDS FOR TWO PHONES, OR ONE FOR ALL

Native apps can use more of the device, but every platform is another version to build, test and update. A web app or PWA reaches any device with a browser, which matters when students use whatever device the family has. Ask what must work offline before choosing.

“Works offline” has degrees. A PWA can usually show pages it has already loaded; saving new work offline and syncing it later is a separate feature to ask for.

B1/THE STACK 3 TERMS

One application deployed whole, or many small ones deployed apart

Two ways to shape a system, and the software that joins systems together.

Monolith

Part

Where you’ll meet it Older or simpler systems.

Microservices

Part

Where you’ll meet it Large platforms.

Middleware

Part

Where you’ll meet it Integration projects.

FIG 34 — ONE APP, MANY SERVICES, AND THE JOIN BETWEEN

Neither shape is a fault. A monolith is simpler to run and suits many products; microservices let large teams change parts separately, at the cost of more moving pieces. Middleware is where integrations often fail quietly, so ask who watches it.

A vendor moving from a monolith to microservices is making a large, slow change. Ask what users will notice during it, and how long the old and new versions will run side by side.

B1/THE STACK 4 TERMS

The cloud question is how much the provider runs for you

Where software runs, and how the work of running it is split between you and a provider.

Cloud

Part

Where you’ll meet it Hosting decisions.

SaaS, PaaS, IaaS

Part

SAY

SASS, PASS, EYE·ass

/sæs, pæs/

Where you’ll meet it Procurement.

On-premises, on-prem

Part

Where you’ll meet it Security-sensitive systems.

Serverless

Part

Where you’ll meet it Small, spiky workloads.

FIG 35 — WHO RUNS EACH LAYER, FROM ON-PREM TO SAAS

Each step to the right hands more of the work to the provider, and more of the control. That is often a good trade, but it moves risk into the contract: uptime, where data is kept, how you leave. On-premises keeps control and keeps all the work, including the calls at 2 a.m.

“Serverless” does not mean there are no servers. It means you never see or manage them, and usually pay for each run rather than for a machine left switched on.

B1/THE STACK 3 TERMS

A virtual machine copies a whole computer. A container packs one app.

Three ways of packing software so that many things can share real machines safely.

Virtual machine (VM)

Part

Where you’ll meet it Hosting.

Container, Docker

Part

Where you’ll meet it “It’s containerised”

Kubernetes, K8s

Part

SAY

koo·ber·NET·eez, KAYTS

/ˌkuːbəˈnɛtiːz/

Where you’ll meet it Platform engineering.

FIG 36 — VMS EACH CARRY AN OS. CONTAINERS SHARE ONE

Containers are why “it works on my machine” is heard less often: the app travels with what it needs. Kubernetes is powerful and demanding, and a small service may not need it. If a proposal includes it, ask who will run it day to day.

B1/THE STACK 2 TERMS

DNS finds the server. A CDN puts a copy of the page close by.

What happens between typing an address and seeing the page.

CDN (content delivery network)

Part

Where you’ll meet it Fast-loading pages and videos.

Domain, DNS (domain name system)

Part

Where you’ll meet it Launches and outages.

FIG 37 — A DOMAIN LOOKED UP, THEN SERVED FROM NEARBY

Both are quiet until they fail, and then everything fails. A DNS mistake can take a whole site offline, so ask who controls the domain and when it renews. A CDN is the usual answer when a video or a results page must load fast for everyone at once.

Domains lapse more often than people expect. Keep the registration in the organisation’s name, with a shared contact rather than one person’s email.

B1/THE STACK 3 TERMS1 DEFECT

Who owns the code shapes how hard it is to leave

Three words for the long life of a system: who owns its code, how old it is and what it costs to leave.

Open source, proprietary

Part

Where you’ll meet it Procurement and risk.

Legacy system

Status

Where you’ll meet it Migration projects.

Vendor lock-in

Defect

Where you’ll meet it Procurement reviews.

FIG 38 — OWNED, OPEN, OLD, AND THE COST OF LEAVING

Lock-in is rarely signed for; it builds up through data formats, integrations and habits. Ask at procurement how data comes out, and in what format. Open source lowers one barrier but not all of them. A legacy system often stays because it works and nobody can safely change it.

Proprietary software built on open-source libraries is normal. The licence terms of those libraries still apply, which is a question for the vendor, not a reason for alarm.

CODE AND DATA

Part two of three

The raw material

You don’t need to read code to work with engineers, but these words come up whenever someone explains why a change is harder than it looks.

Thirty terms on 10 plates: 25 parts, one measure, two stages and two defects.

The defects to watch for here: hardcoded and magic number. Appendix B collects every defect by family.

B2/CODE AND DATA 5 TERMS

Code is named parts: values, jobs, templates and notes to people

One short file, with its parts named: the words engineers use when they point at code.

Source code, codebase

Part

Where you’ll meet it “It’s buried deep in the codebase”

Function, method

Part

Where you’ll meet it Code reviews.

Variable

Part

Where you’ll meet it Code reviews.

Class, object

Part

Where you’ll meet it Architecture discussions.

Comment

Part

Where you’ll meet it Code reviews.

FIG 39 — ONE FILE OF SOURCE CODE, ITS PARTS NAMED

You do not need to read code to follow a review, but these names tell you where a problem sits. A comment that says why, not what, is a sign of care. A codebase that only one person understands is a risk however good the code is.

B2/CODE AND DATA 4 TERMS

Your code is split into modules and leans on packages others wrote

How a codebase is divided up, and how it pulls in code written elsewhere.

Module

Part

Where you’ll meet it “The grading module”

Dependency

Part

Where you’ll meet it Security patches and upgrades.

Package, package manager

Part

Where you’ll meet it Setting up a project.

Script

Part

Where you’ll meet it “I’ll write a script for that”

FIG 40 — MODULES INSIDE, PACKAGES PULLED IN

Most of a modern app is code its own team did not write. Every dependency is a supplier, with its own updates and security fixes, so ask how they are kept current. A script is often a one-off that quietly becomes part of how the system runs; ask where it lives and who owns it.

B2/CODE AND DATA 4 TERMS2 DEFECTS

Values that change belong in config, not written into the code

Where a setting lives decides who can change it, and how long the change takes.

Config, configuration file

Part

Where you’ll meet it Deployments.

Environment variable

Part

Where you’ll meet it Deployments.

Hardcoded

Defect

Where you’ll meet it “The term dates are hardcoded”

Magic number

Defect

Where you’ll meet it Code reviews.

FIG 41 — THE SAME THREE VALUES, IN CODE AND IN CONFIG

“The term dates are hardcoded” means a new term needs an engineer and a release, not an edit. Ask which values the school or ministry will want to change each year, and check they can be configured. Secrets such as keys belong in environment variables, never in the code.

B2/CODE AND DATA 2 TERMS

Boilerplate only sets the stage. A refactor changes form, not results.

Two words for code that does no new work: the set-up every project repeats, and the tidying that leaves behaviour as it was.

Boilerplate code

Part

Where you’ll meet it Starter templates and generators.

Refactor

Stage

Where you’ll meet it “We need a sprint to refactor before adding features”

FIG 42 — SET-UP CODE, THEN A REFACTOR THAT KEEPS RESULTS

A sprint spent refactoring delivers nothing users can see, and that is the point: it makes the next features cheaper and safer to build. Ask how the team will show that nothing changed, which usually means tests that pass before and after. Boilerplate is rarely worth arguing over; templates and generators write most of it.

Refactoring is easy to postpone and costly to postpone for long. A team asking for time to refactor is usually describing code that has become slow to change.

B2/CODE AND DATA 2 TERMS

One record, four plain-text formats, each suited to a different job

The formats data travels in between systems, shown carrying the same student record.

JSON

Part

SAY

JAY·sun

/ˈdʒeɪsən/

Where you’ll meet it API responses and exports.

CSV, XML, YAML

Part

SAY

see·ess·VEE, ex·em·ELL, YAM·ul

/ˈjæməl/

Where you’ll meet it Imports, exports and configs.

FIG 43 — ONE STUDENT RECORD IN FOUR FORMATS

All four are plain text, so any of them can be opened and checked. CSV is the one most likely to reach a teacher, through a spreadsheet, and the one most easily damaged: a spreadsheet may drop a leading zero or reformat a date. Ask for exports in a documented format.

B2/CODE AND DATA 2 TERMS

A query asks the database a question, in the language it speaks

The same question asked of two kinds of database.

SQL, NoSQL

Part

SAY

ESS·kyoo·ell or SEE·kwul, no·SEE·kwul

/ˈsiːkwəl/

Where you’ll meet it Data and reporting work.

Query

Part

Where you’ll meet it Reports and dashboards.

FIG 44 — ONE QUESTION, ASKED IN SQL AND IN NOSQL

Every report and dashboard is a query underneath. When a number looks wrong, the query is the first place to look: a filter left out, a date range off by one. Asking to see the query behind a figure is a fair request, not a technical one.

B2/CODE AND DATA 4 TERMS

The schema says what each field in the table holds

One small table of students, with its structure and its keys named.

Schema

Part

SAY

SKEE·muh

/ˈskiːmə/

Where you’ll meet it “That needs a schema change”

Table, row, field

Part

Where you’ll meet it Data discussions.

ID, primary key, UUID

Part

Where you’ll meet it “Match on student ID”

Data types

Part

Where you’ll meet it Bugs where a number is stored as text.

FIG 45 — A TABLE OF STUDENTS, ITS SCHEMA AND KEYS

Match records on an ID, never on a name: two students can share a name, and names change. Many reporting bugs are data-type bugs, such as scores stored as text, which sort 100 before 42. A schema change is real work, so expect it to be planned, not slipped in.

B2/CODE AND DATA 3 TERMS

Dates, names and patterns look simple and break in quiet ways

Three kinds of text behind the bugs users notice first: wrong times, garbled names and rejected email addresses.

Timestamp, UTC, ISO 8601

Measure

Where you’ll meet it Logs, exports and time-zone bugs.

Unicode, UTF-8

Part

Where you’ll meet it Garbled Chinese or Tamil names.

Regex (regular expression)

Part

SAY

REJ·eks

/ˈrɛdʒɛks/

Where you’ll meet it Form validation.

FIG 46 — A TIME, A NAME AND AN EMAIL RULE

Store times in UTC and show them in local time, or a 9 a.m. deadline can appear as 1 a.m. A system that garbles a Tamil or Chinese name has an encoding fault, not a user error. A pattern that is too strict turns real addresses away. Test with real names and addresses before launch.

B2/CODE AND DATA 2 TERMS

What is remembered between clicks, and where it is kept

How a site remembers who you are, and keeps answers close at hand for speed.

Cache

Part

SAY

KASH

/kæʃ/

Where you’ll meet it “Clear your cache and try again”

Cookie, session

Part

Where you’ll meet it Logins and privacy notices.

FIG 47 — A COOKIE, A SESSION AND A CACHE IN ONE REQUEST

“Clear your cache” works because the browser was showing an old copy. A cache makes things fast and can make them briefly wrong, such as a mark updated but not yet shown. Session length is a policy choice: shared school computers need short ones.

B2/CODE AND DATA 2 TERMS

Rehearse every migration on fake data before it touches real data

How data is moved to a new structure, and the invented data used to practise.

Seed data, test data

Part

Where you’ll meet it Demos and test environments.

Migration

Stage

Where you’ll meet it Upgrades and platform moves.

FIG 48 — SEED DATA FOR THE REHEARSAL, THEN THE REAL RUN

A migration is one of the riskiest steps in any upgrade, because it changes the records themselves. Ask whether it has been rehearsed on a full-size copy, how long it takes and how it is undone. Test data should be invented, not a copy of real students’ records.

VERSION CONTROL

Part two of three

Version control and code review

Every change to code is recorded, reviewed and merged. This is the engineering equivalent of track changes, sign-off and version history, and it is far stricter than most document workflows.

Twenty-seven terms on nine plates: 14 parts, seven stages, three statuses, one role and two defects.

The defects to watch for here: merge conflict and stale branch. Appendix B collects every defect by family.

In the field guides.

B3/VERSION CONTROL 5 TERMS

Git keeps the history. GitHub is where teams keep Git.

Five words for where code and its history live, from the idea of version control to the sites that host it.

Version control

Part

Where you’ll meet it Every software team.

Git

Part

Where you’ll meet it “Is it in Git?”

GitHub, GitLab, Bitbucket

Part

Where you’ll meet it Team tooling.

Repository, repo

Part

Where you’ll meet it “Send me the repo link”

Monorepo

Part

Where you’ll meet it Large organisations.

FIG 49 — TWO LAPTOPS, TWO REPOSITORIES AND ONE MONOREPO

Git is the tool; GitHub, GitLab and Bitbucket are websites built around it, so “we use Git” does not say where the code is kept. In a contract, ask whose account holds the repository. The code and its whole history should belong to the school or ministry, not sit in a vendor’s private account.

One repository or many is an engineering choice with costs either way. For whoever commissions the work, the useful question is simpler: can we have a full copy of every repository, with its history, at any time?

B3/VERSION CONTROL 3 TERMS

Each commit is a saved step. Main is the line that counts.

Three words for the shape of a project’s history: the steps, the side lines and the line everyone builds on.

Commit

Part

Where you’ll meet it “Which commit broke it?”

Branch

Part

Where you’ll meet it “It’s on a feature branch”

Main, trunk

Part

Where you’ll meet it “Merged to main”

FIG 50 — THREE COMMITS ON A BRANCH, JOINED BACK TO MAIN

A good commit message says why, not only what, and it is how a team later finds the change that broke results day. Work on a branch is invisible to users, and to most of the team, until it joins main. “It’s done on my branch” is not done.

B3/VERSION CONTROL 3 TERMS

A pull request is a change asking to join. The diff is the change.

Three words for how a change is proposed: the request, its early draft and the exact lines it alters.

Diff

Part

Where you’ll meet it Code reviews.

Pull request (PR), merge request (MR)

Part

Where you’ll meet it “I’ve opened a PR”

Draft PR

Status

Where you’ll meet it Early feedback.

FIG 51 — A DRAFT PULL REQUEST AND THE DIFF IT CARRIES

The diff is the honest size of a change. A short description can sit on top of hundreds of changed lines, and a reviewer can vouch only for what they can read, so large pull requests get weaker reviews. A draft PR invites comment early, before anyone spends a week on the wrong approach.

GitHub and Bitbucket say pull request; GitLab says merge request. They name the same thing.

B3/VERSION CONTROL 3 TERMS

A reviewer reads the change. An approver decides it can go in.

Three words for code review: the practice, the people in it and the two verdicts they can give.

Code review

Stage

Where you’ll meet it Every change in a healthy team.

Reviewer, approver

Role

Where you’ll meet it Pull requests.

Approve, request changes

Status

Where you’ll meet it Pull requests.

FIG 52 — ONE REVIEW: CHANGES REQUESTED, THEN APPROVED

Request changes is not a rejection; it is the review doing its job. What matters to a commissioner is that every change to the main code is read by someone who did not write it, and that the tooling enforces the rule rather than good intentions. Ask whether anyone can merge their own change.

B3/VERSION CONTROL 2 TERMS

Merged means it is in the main code. It does not mean it is live.

Two words for the moment a branch joins main, and the status update most often misread.

Merge

Stage

Where you’ll meet it “Merged this morning”

Merged

Status

Where you’ll meet it Status updates.

FIG 53 — MERGED ON MONDAY, LIVE ON THURSDAY

“Merged this morning” is an engineering milestone, not a release. Between the merge and users there is still a build, tests, a deploy and often a feature flag, which can take hours or weeks. When a status update says merged, ask when it will be live, and for whom.

B3/VERSION CONTROL 2 TERMS

Clone to work on a copy. Push and pull to keep copies in step.

Two pairs of words for copying a repository and moving commits between the copies.

Clone, fork

Stage

Where you’ll meet it Contributing to projects.

Push, pull

Stage

Where you’ll meet it Daily work.

FIG 54 — ONE SHARED REPOSITORY, TWO CLONES AND A FORK

Every engineer works on a clone, so the shared repository is the copy that counts, not anyone’s laptop: work that has not been pushed exists on one machine only. A fork matters most with vendors and open source. It is a separate copy that can drift from the original for good.

B3/VERSION CONTROL 3 TERMS

Rebase tidies history, cherry-pick copies a fix, revert undoes one.

Three ways to move or undo commits without starting the work again.

Rebase

Stage

Where you’ll meet it Engineering debates.

Cherry-pick

Stage

Where you’ll meet it Urgent fixes.

Revert

Stage

Where you’ll meet it “Revert it and we’ll investigate”

FIG 55 — A REBASE, A CHERRY-PICK AND A REVERT

Revert is the one to know. It undoes a change by adding a new commit, so the history still shows what happened and when. Cherry-pick is how one urgent fix reaches the version schools are on without bringing everything else along. Rebase is largely a matter of team taste, and teams argue about it.

B3/VERSION CONTROL 4 TERMS

A repository can explain itself: what it is and what changed.

Four records that let a newcomer, an auditor or a vendor’s successor read a project without its authors.

Tag

Part

Where you’ll meet it Releases.

Changelog, release notes

Part

Where you’ll meet it Release announcements.

README

Part

Where you’ll meet it Opening any repo.

Blame

Part

Where you’ll meet it Investigating bugs.

FIG 56 — WHAT ONE REPOSITORY RECORDS ABOUT ITSELF

Release notes are the record a school will see, so ask for them to be written for teachers, not engineers. Blame sounds like an accusation and is not one: it shows who last touched each line, which is usually the quickest way to find the person who knows why. A missing README is an early sign of a project only its author can run.

B3/VERSION CONTROL 2 TERMS2 DEFECTS

Branches left too long drift away, and drifting branches collide.

Two defects of branches kept apart too long: one builds up slowly, the other arrives all at once.

Merge conflict

Defect

Where you’ll meet it Busy codebases.

Stale branch

Defect

Where you’ll meet it Abandoned work.

FIG 57 — A BRANCH LEFT FOR MONTHS, THEN A CONFLICT

A stale branch is work paid for and not delivered. The longer it waits, the more main moves on and the costlier the merge. Small conflicts are routine; large ones are a warning. If a vendor reports weeks of “merging”, ask how long their branches live.

SHIPPING

Part two of three

Building, testing and shipping

The path from a merged change to something users can touch. Most of the reassuring words here, such as canary, feature flag and rollback, exist to make a release reversible.

Thirty-eight terms on 13 plates: 10 parts, two measures, 18 stages and eight statuses.

In the field guides.

B4/SHIPPING 5 TERMS

Every change goes down the pipeline. One failed check turns it red.

Five words for the automation that turns every change into tested software that can run.

Build

Stage

Where you’ll meet it “The build is broken”

Compile

Stage

Where you’ll meet it Build logs.

CI/CD (continuous integration, continuous delivery)

Part

Where you’ll meet it Engineering tooling.

Pipeline

Part

Where you’ll meet it “It failed in the pipeline”

Green build, red build

Status

Where you’ll meet it Pull requests and dashboards.

FIG 58 — TWO RUNS OF ONE PIPELINE, GREEN AND RED

A red build is the system working: it stopped a fault before users met it. The warning sign is a team that ignores red builds, or switches failing tests off to get green. Ask how long the pipeline takes and how often main is red; a slow pipeline is one people learn to work around.

B4/SHIPPING 5 TERMS

The same system, copied several times. Only one copy is live.

The copies a change passes through, from an engineer’s laptop to the live system, and the sandbox kept apart from them.

Environment

Part

Where you’ll meet it “Which environment are you on?”

Local, dev

Part

Where you’ll meet it Bug reports.

Staging

Part

Where you’ll meet it “It’s on staging for UAT”

Production, prod

Part

Where you’ll meet it “Is it in prod yet?”

Sandbox

Part

Where you’ll meet it Vendor trials and training.

FIG 59 — FOUR COPIES OF ONE SYSTEM, AND A SANDBOX APART

Many “it works for me” arguments are two people on different environments, so a bug report should always name one. Staging is useful only if it stays close to production. A sandbox is for vendor trials and training, and should hold made-up records, not real students.

When a vendor demonstrates a product, ask which environment it is. A demo on a sandbox with ten tidy records says little about production with a whole cohort in it.

B4/SHIPPING 2 TERMS

QA asks whether it works. UAT asks whether it is what we wanted.

Two kinds of testing by people: testers hunting defects, then the business confirming the fit.

QA (quality assurance)

Stage

Where you’ll meet it Release schedules.

UAT (user acceptance testing)

Stage

Where you’ll meet it The step before go-live.

FIG 60 — QA BY TESTERS, THEN UAT BY THE PEOPLE WHO ASKED

UAT is the step a ministry or school owns, and it is the first to be squeezed when a project runs late. Plan it from the start: name the teachers or officers who will test, book their time, and agree what “accepted” means before the build arrives. Signing off UAT is a business decision.

B4/SHIPPING 3 TERMS

Many small tests at the base, a few whole journeys at the top.

Three sizes of automated test, from one small piece of code to a whole user journey.

Unit test

Stage

Where you’ll meet it Code reviews.

Integration test

Stage

Where you’ll meet it CI pipelines.

End-to-end (E2E) test

Stage

Where you’ll meet it Release checks.

FIG 61 — MANY SMALL TESTS, FEWER LARGE ONES

Each size catches different faults. Unit tests are fast and point at the broken line, but cannot see two parts disagreeing. End-to-end tests catch that, but are slow and fail for unrelated reasons. A suite of only one kind is either slow and fragile or passes while the system fails.

B4/SHIPPING 3 TERMS

Each test guards a moment: every release, every deploy, every peak.

Three tests named for when they run and what they protect against.

Regression test

Stage

Where you’ll meet it Every release.

Smoke test

Stage

Where you’ll meet it Right after a deploy.

Load test, stress test

Stage

Where you’ll meet it Before peak periods such as exams.

FIG 62 — THREE TESTS ACROSS ONE TERM OF RELEASES

Load-test against the real peak, not an ordinary Tuesday: the first morning of term, results day, the night before a deadline. A stress test then finds where it breaks, so the team knows its margin. A smoke test after every deploy takes minutes and catches the release that will not start at all.

B4/SHIPPING 2 TERMS

A linter reads the code. Coverage counts what the tests reach.

Two automatic signals of code quality that appear on dashboards and in every pull request.

Test coverage

Measure

Where you’ll meet it Quality dashboards.

Linter

Part

Where you’ll meet it Every commit.

FIG 63 — A LINT WARNING AND A COVERAGE REPORT

Both are useful and both are easy to game. High coverage says the code ran during the tests, not that the tests checked anything that matters, so a target of 100% can produce tests that assert nothing. Ask which important paths, such as calculating grades, are covered.

B4/SHIPPING 2 TERMS

A mock stands in for one service; parity lets a system stand in

Two kinds of stand-in: a fake part inside a test, and a new system ready to replace an old one.

Mock, stub

Part

Where you’ll meet it Unit tests that don’t call the real payment service.

Feature parity

Status

Where you’ll meet it The usual sticking point in migrations.

FIG 64 — A MOCK IN A TEST, A NEW SYSTEM ONE SHORT

A test that uses a mock checks the code, not the real service, so a green test says nothing about whether the payment provider is up. Feature parity is where migrations stall: the old system’s odd reports are features to someone. List them early, and agree which will be dropped rather than finding out after the switch.

Parity is rarely the right goal in full. Some old features exist only to work around old limits; ask which ones users would miss before paying to rebuild them.

B4/SHIPPING 3 TERMS

Deploy puts it on the servers. Release puts it in front of users.

Three words for getting work out, which status updates often treat as one.

Deploy

Stage

Where you’ll meet it “Deployed to staging”

Release

Stage

Where you’ll meet it Product announcements.

Ship

Stage

Where you’ll meet it “We shipped it Friday”

FIG 65 — DEPLOYED TO THE SERVERS, THEN RELEASED TO USERS

The gap between deploy and release is useful: code can sit on the live servers, switched off, until the school or the policy is ready. Ship is the informal word, and it is sometimes said at deploy. When someone says it shipped, ask whether users can see it yet.

B4/SHIPPING 3 TERMS

Release to a few, watch, then to everyone. The flag can undo it.

Three ways to make a release gradual and reversible, usually used together.

Rollout, phased rollout

Stage

Where you’ll meet it Large user bases.

Feature flag, toggle

Part

Where you’ll meet it Controlled launches.

Canary release

Stage

Where you’ll meet it Risky changes.

FIG 66 — A FLAG, A CANARY AND A ROLLOUT OVER ONE WEEK

For schools the canary is often a few volunteer schools, which also makes it a pilot with real users. Ask what is watched at each step, what number would stop the rollout, and who can turn the flag off at 7 a.m. on a school day without waiting for a deploy.

B4/SHIPPING 2 TERMS

Keep the old version running, and going back takes a minute.

Two words for switching between versions: a deployment that keeps both, and the step back.

Blue-green deployment

Stage

Where you’ll meet it Zero-downtime releases.

Rollback

Stage

Where you’ll meet it “Roll it back now”

FIG 67 — TRAFFIC SWITCHED BACK FROM GREEN TO BLUE

Before a large release, ask for the rollback plan and when it was last practised. Blue-green makes rollback a switch rather than a rebuild. Watch for changes that cannot be undone this way, such as a database change the old version cannot read.

B4/SHIPPING 2 TERMS

Every version has a life: tested, released, supported, then ended.

Two sets of labels for where a version stands, before its release and after it.

Alpha, beta, GA (general availability)

Status

Where you’ll meet it Product launches.

LTS (long-term support), EOL (end of life)

Status

Where you’ll meet it Upgrade planning.

FIG 68 — TWO VERSIONS, FROM ALPHA TO END OF LIFE

Before buying, ask where the product sits on this line. Beta means known gaps, so do not plan exam use on it. After launch, the end-of-life date matters as much as the features: a version past EOL gets no security fixes, and the upgrade becomes urgent rather than planned.

B4/SHIPPING 4 TERMS

The first number warns of breakage. The other two promise none.

Four words for what a version number promises to the systems that depend on it.

SemVer (semantic versioning)

Measure

Where you’ll meet it Release notes.

Breaking change

Status

Where you’ll meet it Upgrade warnings.

Backward compatible

Status

Where you’ll meet it Upgrade notes.

Deprecated

Status

Where you’ll meet it API notices.

FIG 69 — THREE VERSION NUMBERS AND WHAT EACH PROMISES

A new major version is a warning to everything connected, such as a school’s reports that pull from an API. Deprecation notices are the early signal and are easy to miss, so someone should own reading them. Not every product follows SemVer strictly: ask the vendor what their numbers promise.

B4/SHIPPING 2 TERMS

During a freeze nothing ships, except the fix that cannot wait.

Two words for the calendar of change: the quiet period around exams, and the exception to it.

Hotfix, patch

Stage

Where you’ll meet it Live incidents.

Code freeze, change freeze

Status

Where you’ll meet it Exams, year-end and holidays.

FIG 70 — A FREEZE OVER EXAMS, AND ONE HOTFIX INSIDE IT

Put freezes in the plan at the start of the year: exam weeks, results release, the start of term. Teams then aim to finish before them, not during. Agree in advance who can approve a hotfix in a freeze, so the decision on the night is quick and nobody goes around the rule.

WEB AND APIS

Part two of three

Web, APIs and integration

How software talks to browsers and to other software, and the learning-technology standards that decide whether an education platform can exchange content, scores and class lists with other systems.

Twenty-eight terms on 10 plates: 24 parts, three measures and one stage.

The second half of the family is the learning-technology standards: LTI, SCORM, xAPI, QTI and OneRoster. They are the reason one platform can launch another’s tool and get the scores back.

B5/WEB AND APIS 4 TERMS

Three languages write a page; the browser turns it into the DOM

The files a team writes, and what the browser makes of them on someone’s screen.

HTML, CSS, JavaScript (JS)

Part

Where you’ll meet it Front-end work.

TypeScript (TS)

Part

Where you’ll meet it Modern front-end teams.

Browser

Part

Where you’ll meet it “Which browser were you on?”

DOM (document object model)

Part

Where you’ll meet it Front-end bugs.

FIG 71 — FROM FILES TO THE PAGE A STUDENT SEES

When a page “looks wrong in one browser”, the cause is usually how that browser reads the CSS or runs the JavaScript, so the first question is which browser and which version. TypeScript is a team choice that catches mistakes before release; users never see it, because the browser only ever runs JavaScript.

The DOM is why a page can change without reloading: code edits the browser’s live model, and the screen follows. Many front-end bugs are a gap between what the HTML said and what the DOM has since become.

B5/WEB AND APIS 4 TERMS

Every click is a request, and every reply carries a number

What travels between a browser and a server when someone opens a link.

URL

Part

Where you’ll meet it Every link.

HTTP, HTTPS

Part

Where you’ll meet it Security checks.

Request, response

Part

Where you’ll meet it API documentation.

Status code

Measure

Where you’ll meet it Error pages and bug reports.

FIG 72 — ONE REQUEST AND TWO POSSIBLE RESPONSES

A status code in a bug report saves a day of guessing. 404 means the address is wrong or the page has gone; 403 means the server understood and refused; 500 means the server itself failed. Ask for the code and the URL, not only a screenshot of the error page.

HTTPS encrypts the request and the response on the way, which is why it is the minimum for any page that carries a student’s name or a password.

B5/WEB AND APIS 3 TERMS

An API answers when asked; a webhook speaks when something happens

Two ways one system learns what another knows, and the connection they make together.

REST, GraphQL

Part

Where you’ll meet it Integration specifications.

Webhook

Part

Where you’ll meet it “Fire a webhook when a submission arrives”

Integration

Part

Where you’ll meet it Project scopes.

FIG 73 — TWO WAYS TO ASK, AND ONE WAY TO BE TOLD

If the grades system must keep asking the homework app “anything new?”, marks arrive late and the app is called for nothing. A webhook turns that round: the app announces each submission as it lands. REST or GraphQL is the engineers’ choice; what to ask is which events send a message, and what happens when one fails to arrive.

“Integration” in a project scope promises a working connection, not a particular style. Ask which way data flows, how often, and who fixes it when one side changes.

B5/WEB AND APIS 3 TERMS

A key says which program is calling; OAuth says on whose behalf

Three controls on a program that calls an API: who it is, whom it acts for, and how often it may call.

API key

Part

Where you’ll meet it Integration set-up. Never share it in email or chat.

Rate limit

Measure

Where you’ll meet it Integrations that suddenly stop working.

OAuth

Part

SAY

OH·awth

/ˈəʊɔːθ/

Where you’ll meet it “Sign in with Google” permission screens.

FIG 74 — A KEY, A CONSENT SCREEN AND A CAP

An API key is a password for a program, so it never belongs in an email, a slide or a chat. OAuth lets a teacher give a tool access to her classes without handing over her password, and lets her take it back. When an integration “suddenly stops working” on a busy day, check the rate limit first.

Rate limits tend to bite on the days that matter most, such as the start of term, when every school syncs at once. Ask the vendor what the limit is and what their system does when it is reached.

B5/WEB AND APIS 2 TERMS

An iframe shows another site; CORS decides who may read its data

Two ways a page reaches beyond its own website, and the browser rule that polices one of them.

iframe, embed

Part

Where you’ll meet it Embedded videos and tools.

CORS (cross-origin resource sharing)

Part

SAY

KORZ

/kɔːz/

Where you’ll meet it Integration errors.

FIG 75 — ONE LESSON PAGE REACHING THREE OTHER SITES

Embedding a video or a tool in a lesson page is usually simple, though some sites refuse to be framed. Fetching another site’s data is different: the browser checks whether that server allows this site, and blocks the request if not. A CORS error is a setting on the other server, so the fix sits with whoever runs it.

B5/WEB AND APIS 2 TERMS

Public pages are built to be found; an app is built to be used

Two concerns that pull a website in different directions.

SPA (single-page application)

Part

Where you’ll meet it Modern web apps.

SEO (search engine optimisation)

Part

Where you’ll meet it Public websites.

FIG 76 — A SITE MADE TO BE FOUND, AN APP MADE TO BE USED

A school’s public website needs to be found, so each page needs its own address and readable content, which is what SEO work checks. A homework app behind a sign-in has no need to rank, and a single-page app suits it: it feels quick because only the data changes. Trouble starts when a public site is built like an app and search engines see little but an empty shell.

B5/WEB AND APIS 3 TERMS

Built for every language, every reader, every connection

Three kinds of reach a web platform has to be built for: the languages its users read, the ways they read, and the lines they read on.

i18n, l10n

Stage

Where you’ll meet it Supporting English, Chinese, Malay and Tamil.

Semantic HTML, ARIA

Part

Where you’ll meet it Accessibility fixes.

Bandwidth (network)

Measure

Where you’ll meet it Video lessons on home broadband.

FIG 77 — FOUR LANGUAGES, A SCREEN READER, A SLOW LINE

Each is cheap at the start and costly to add later. Ask whether Chinese and Tamil were tested with real text, whether the site works with a screen reader and a keyboard alone, and how a video lesson behaves on a weak home connection. A platform tested only on the office network has been tested in the wrong place.

Semantic HTML is the cheapest accessibility work there is: a real button is announced as a button with no extra effort. ARIA is for the custom widgets that HTML has no element for.

B5/WEB AND APIS/LEARNING-TECHNOLOGY STANDARDS 3 TERMS

The SIS knows who is in which class; the LMS is where they learn

The two systems at the centre of a school’s data, and the standard that keeps their class lists in step.

LMS (learning management system)

Part

Where you’ll meet it School and university platforms.

SIS (student information system)

Part

Where you’ll meet it Rostering and reporting.

OneRoster

Part

Where you’ll meet it Syncing classes between SIS and LMS.

FIG 78 — CLASS LISTS ONE WAY, GRADES THE OTHER

When the class lists in the LMS go stale, teachers see last term’s students and new ones cannot find their work. The SIS is the source of truth; the LMS should copy from it, not be typed into by hand. Asking a vendor “do you support OneRoster, and which version?” can turn an integration project into a set-up task.

OneRoster also carries grades back the other way, so marks entered in the LMS can reach reports without being keyed in twice.

B5/WEB AND APIS/LEARNING-TECHNOLOGY STANDARDS 2 TERMS

LTI plugs a tool into the platform; QTI moves the questions

Two 1EdTech standards with similar names and different jobs.

LTI (Learning Tools Interoperability)

Part

Where you’ll meet it Plugging third-party tools into a platform.

QTI (Question and Test Interoperability)

Part

Where you’ll meet it Moving question banks between systems.

FIG 79 — A TOOL LAUNCHED, A QUESTION BANK MOVED

LTI is about tools: a teacher opens a third-party tool from inside the LMS, already signed in, and the score comes back to the gradebook. QTI is about content: a bank of questions leaves one system and arrives in another intact. A vendor who supports one may not support the other, so ask about each by name.

B5/WEB AND APIS/LEARNING-TECHNOLOGY STANDARDS 2 TERMS

SCORM records a course finished; xAPI records what learners did

An older and a newer way to keep track of learning, and where each keeps its records.

SCORM

Part

SAY

SKORM

/skɔːm/

Where you’ll meet it Legacy course content.

xAPI, LRS (learning record store)

Part

Where you’ll meet it Learning analytics.

FIG 80 — SCORM IN THE LMS, XAPI FROM ANYWHERE

SCORM packages run inside an LMS and report back mainly completion, a score and time spent. xAPI statements can come from anywhere, such as a simulation, a video or a field-trip app, and collect in an LRS. Plenty of good content still ships as SCORM; the question is whether the record you need is a completion or a pattern of activity.

SECURITY

Part two of three

Security and data protection

The words that come up when a system holds student or staff data. Two pairs cause the most confusion: authentication against authorisation, and encryption at rest against encryption in transit.

Thirty terms on 10 plates: 19 parts, one measure, four stages and six defects.

The defects to watch for here: vulnerability, exploit, zero-day, phishing, social engineering, malware, ransomware and data breach. Appendix B collects every defect by family.

In the field guides.

B6/SECURITY 4 TERMS

Authentication asks who you are; authorisation asks what you may do

The four words for getting into a system, and the question each one answers.

Authentication (authn)

Part

Where you’ll meet it Sign-in flows.

Authorisation (authz)

Part

Where you’ll meet it Teacher vs student access.

SSO (single sign-on)

Part

Where you’ll meet it School and agency platforms.

MFA, 2FA (multi-factor, two-factor authentication)

Part

Where you’ll meet it Account security.

FIG 81 — ONE SIGN-IN, THEN A DECISION PER SYSTEM

A teacher who signs in but cannot see her class has passed authentication and failed authorisation: the fix is a permission, not a password reset. SSO means one sign-in opens many systems, which makes MFA on that one sign-in matter more, not less.

Authn and authz are abbreviated that way because the full words look so alike. In a bug report, “can’t get in” is ambiguous; “can sign in but can’t see 3B” is not.

B6/SECURITY 2 TERMS

Grant permissions by role, and give each role only what it needs

How a platform decides who may do what, and the rule for drawing those lines.

RBAC (role-based access control)

Part

Where you’ll meet it Platform administration.

Least privilege

Part

Where you’ll meet it Security reviews.

FIG 82 — A ROLES FILE, WITH ONE PERMISSION NARROWED

Roles keep permissions manageable across thousands of teachers and students: change the role, and everyone in it changes. Least privilege is the discipline on top. An export job that can read every record is a breach waiting for a reason; one that can read only the marks it sends is a far smaller risk.

B6/SECURITY 3 TERMS

Encryption protects data stored and moving; a hash cannot be undone

Three ways a system keeps data unreadable to anyone who should not read it.

Encryption at rest, in transit

Part

Where you’ll meet it Security questionnaires.

TLS, SSL

Part

Where you’ll meet it Certificates and browser padlocks.

Hashing

Part

Where you’ll meet it How passwords should be stored.

FIG 83 — ENCRYPTED IN TRANSIT AND AT REST; ONE HASH

Security questionnaires ask about at rest and in transit separately because they guard against different things: a stolen disk, and a listener on the network. Passwords are the exception to encryption. They should be hashed, so that not even the vendor can read them back; a vendor who can email you your old password is not hashing it.

B6/SECURITY 2 TERMS

A secret grants access; the audit trail shows who used it

Two things every security review asks about: the keys to a system, and its record of use.

Secret, credential

Part

Where you’ll meet it “Rotate the credentials”

Audit log, audit trail

Part

Where you’ll meet it Investigations and compliance.

FIG 84 — FIVE LINES OF AN AUDIT LOG

Secrets leak through chat messages, shared slides and code pasted into tickets, so treat them like a house key and rotate them when staff or vendors change. The audit log is what lets anyone answer “who looked at this child’s record?” after the fact. Ask how long it is kept and who can read it.

B6/SECURITY 3 TERMS

Named data has a shelf life; de-identified copies can outlive it

What happens to a student’s record over time, and to the copies made from it.

PII (personally identifiable information)

Part

Where you’ll meet it Data protection reviews.

Anonymisation, pseudonymisation

Stage

Where you’ll meet it Research and analytics data.

Retention period

Measure

Where you’ll meet it Data policies.

FIG 85 — ONE STUDENT RECORD AND THE COPIES MADE FROM IT

Pseudonymised data should still be treated as personal data, because whoever holds the key can link it back; only anonymised data is free of that. A retention period turns “keep everything, just in case” into a date on which records are deleted. Ask a vendor how deletion happens, and whether backups follow the same rule.

B6/SECURITY 3 TERMS

Data residency asks where data sits and which law applies

Where a vendor keeps student data, and the laws that bind the vendor.

Data residency

Part

Where you’ll meet it Cloud procurement.

PDPA (Personal Data Protection Act)

Part

Where you’ll meet it Vendor contracts.

GDPR (General Data Protection Regulation)

Part

Where you’ll meet it International vendors.

FIG 86 — ONE VENDOR, TWO STORES, TWO LAWS

The PDPA binds private-sector organisations in Singapore; public agencies follow separate government rules. An international vendor may also follow the GDPR; that is useful to know, but it does not replace what a Singapore contract requires. Ask where the data and its backups physically sit, not only where the company is based.

B6/SECURITY 2 TERMS

A threat model plans for attacks; a pentest tries them

Two security activities at opposite ends of a project.

Threat model

Stage

Where you’ll meet it Early design.

Penetration test, pentest

Stage

Where you’ll meet it Before launch.

FIG 87 — FROM THREAT MODEL TO LAUNCH, WITH A PENTEST

A threat model is cheap early and expensive to skip: it decides what the design must protect before anything is built. A penetration test comes before launch and finds what got through anyway. A pentest that finds nothing at all is worth a second look at what it was allowed to test.

B6/SECURITY 4 TERMS3 DEFECTS

A vulnerability is the gap; an exploit is the way through it

The life of one weakness, from the first attacker who finds it to the last school to patch.

CVE (Common Vulnerabilities and Exposures)

Part

Where you’ll meet it Patch notices.

Vulnerability

Defect

Where you’ll meet it Security reports.

Exploit

Defect

Where you’ll meet it Security advisories.

Zero-day

Defect

Where you’ll meet it Urgent patches.

FIG 88 — ONE VULNERABILITY, FROM DISCOVERY TO PATCH

A zero-day is the worst case because no fix exists yet. Once a fix and a CVE number are published, the risk moves to whoever has not yet patched, and attackers read the same notices. When a vendor’s notice cites a CVE, the questions are simple: are we affected, and when will the fix be in?

B6/SECURITY 3 TERMS3 DEFECTS

An attack can start with a message and end in a breach

Three words for how attacks reach a school, and what they leave behind.

Phishing, social engineering

Defect

Where you’ll meet it Staff training.

Malware, ransomware

Defect

Where you’ll meet it Incident reports.

Data breach

Defect

Where you’ll meet it Incident reports and notifications.

FIG 89 — FROM ONE EMAIL TO A DATA BREACH

Phishing works on busy people, which is why staff training repeats every year. Ransomware locks files for a ransom, and attackers often copy data out first, which turns a disruption into a data breach that may have to be notified. Reporting a suspicious message quickly is worth more than being sure it is an attack.

B6/SECURITY/SINGAPORE PUBLIC-SECTOR TERMS 4 TERMS

One manual, one test, one cloud, one sign-in

Four public-sector terms that a team building a Singapore agency system will meet.

IM8

Part

Where you’ll meet it Agency system projects.

VAPT (vulnerability assessment and penetration testing)

Stage

Where you’ll meet it Launch checklists.

GCC (Government on Commercial Cloud)

Part

Where you’ll meet it Hosting decisions.

Singpass

Part

Where you’ll meet it Citizen-facing services.

FIG 90 — AN AGENCY SYSTEM AND THE FOUR TERMS AROUND IT

Each term lands at a different stage of an agency system project: IM8 from the start, GCC at hosting decisions, Singpass for services that citizens sign in to, and VAPT on the launch checklist. Requirements found late are costly to meet, so raise all four at the start.

WHERE NEXT

Continued in volume two, Runbooks and Roadmaps

VOL 2 Runbooks and Roadmaps · B7–B14 · C1–C2 How software is run, fixed, planned and delivered, the patterns behind it, and the words that mean something else to engineers
INDEX The phrasebooks glossary · every term in the four toolkits, A to Z

This volume ends with its last section, and volume two picks up at section B7. The toolkit closes with the three questions, asked in the team’s own words, at the end of volume two.

The phrasebooks glossary lists every term in all four toolkits and opens it in the volume that holds it.

SOURCES

Thirteen works

The definitions are the source glossary’s own. Where a term rests on a published source, the source is named in the definition and listed here.

VOLUMES Runbooks and Roadmaps The phrasebooks glossary
COMPANIONS Instruments and Moves Marks and Measures
BY geraldajam.com

Most of these terms are trade vocabulary rather than findings, so they have no single source. The few that do, such as technical debt, the SLO, Conway’s law and the strangler fig, cite it in their definition, and Appendix G records what was checked.

Instruments and Moves names what happens in the words. Marks and Measures names what happens on the page. This companion names what happens behind the screen.

Reference layer

Appendix

Appendix A

The A to Z index

All 208 terms in this volume alphabetically, with the family each belongs to, its kind and the source glossary’s definition. The phrasebooks glossary lists the terms of every volume.

Family	Kind	What it means
A4 · Safe and open	Judging	How usable the software is for people with disabilities.
B4 · Shipping	Status	Early internal testing, wider testing with known gaps, and full release.
B6 · Security	Stage	Removing identity from data for good, or replacing it with a code that can be linked back.
B1 · The stack	Part	A defined way for one piece of software to ask another for data or actions.
B5 · Web and APIs	Part	A secret code that identifies a program calling an API.
B3 · Version control	Status	The two verdicts a reviewer can give.
B6 · Security	Part	A tamper-resistant record of who did what, and when.
B6 · Security	Part	Proving who you are.
B6 · Security	Part	Deciding what you’re allowed to do once signed in.
A2 · Staying up	Judging	The share of time the system is up and usable.
B1 · The stack	Part	The servers, databases and logic users never see.
B4 · Shipping	Status	A change that keeps older integrations and data working.
B5 · Web and APIs	Measure	How much data a connection can carry per second. For the “no bandwidth” sense, see B12.
B3 · Version control	Part	A view showing who last changed each line. Neutral, despite the name.
B4 · Shipping	Stage	Running old and new versions side by side, then switching traffic over.
B2 · Code and data	Part	Repetitive set-up code that every project needs. For the editorial sense, see Marks and Measures B3.
B3 · Version control	Part	A separate line of work that can change without affecting the main code.
B4 · Shipping	Status	A change that stops existing integrations or behaviour working.
B5 · Web and APIs	Part	The app that displays web pages: Chrome, Safari, Edge, Firefox.
B4 · Shipping	Stage	Turning source code into software that can run. Also the result.
B2 · Code and data	Part	A stored copy of data kept close at hand for speed.
B4 · Shipping	Stage	Releasing to a small group first to catch problems early.
B1 · The stack	Part	Servers around the world that hold copies of content close to users.
B3 · Version control	Part	A record of what changed in each version, for engineers or for users.
B3 · Version control	Stage	Copying one specific change from one branch to another.
B4 · Shipping	Part	Automation that builds and tests every change, then delivers it towards release.
B2 · Code and data	Part	A template for a kind of thing in code, and one instance of it.
B1 · The stack	Part	The user’s device or app that asks, and the computer that answers.
B3 · Version control	Stage	Copying a repository to your machine, or into a separate copy you own.
B1 · The stack	Part	Computing rented from a provider over the internet, such as AWS, Azure or Google Cloud.
B4 · Shipping	Status	A period when no changes may be released.
B3 · Version control	Stage	Another engineer reads and comments on a change before it is merged.
A3 · Change	Judging	How well the code in one part belongs together. High cohesion is the goal.
B2 · Code and data	Part	A note in code for humans, ignored by the computer.
B3 · Version control	Part	One saved change, with a message explaining it.
B4 · Shipping	Stage	Translating code into a form the computer runs directly.
A3 · Change	Judging	How many moving parts and paths the code has.
B2 · Code and data	Part	Settings kept outside the code so they can change without rewriting it.
B1 · The stack	Part	A packaged app with everything it needs to run anywhere. Docker is the common tool.
B2 · Code and data	Part	A small file a website stores in your browser, and the period you stay logged in.
B5 · Web and APIs	Part	Browser rules on which sites may request data from which servers.
A3 · Change	Judging	How tightly parts depend on each other. Loose coupling is the goal.
B2 · Code and data	Part	Other plain-text data formats: tables, tagged documents and settings files.
B6 · Security	Part	A public catalogue number for a known vulnerability.
B6 · Security	Defect	Unauthorised access to or release of data.
B6 · Security	Part	Where data is physically stored, and under which country’s law.
B2 · Code and data	Part	The kind of value a field holds: string (text), integer (whole number), boolean (true or false), null (empty)
B1 · The stack	Part	Organised, stored data the system reads and writes.
B2 · Code and data	Part	Outside code a project relies on. Two meanings: also a task that waits on another (B9)
B4 · Shipping	Stage	Putting a build onto an environment’s servers.
B4 · Shipping	Status	Still works but scheduled for removal. Stop using it.
A4 · Safe and open	Judging	How easy and pleasant a tool, platform or API is for engineers to use.
B3 · Version control	Part	The exact lines added and removed between two versions.
B5 · Web and APIs	Part	The browser’s live model of a page, which code changes to update what you see.
B1 · The stack	Part	A web address, and the system that turns it into a server location.
B3 · Version control	Status	A pull request opened early to show work in progress, not yet ready for review.
B6 · Security	Part	Scrambling stored data, and scrambling data as it travels.
B4 · Shipping	Stage	A test of a whole user journey, start to finish.
B1 · The stack	Part	One specific address on an API, such as the one that returns a class list.
B4 · Shipping	Part	A separate copy of the system for one purpose. Two meanings: see Part C.
B2 · Code and data	Part	A setting supplied by the server where code runs, often a secret such as a key.
B6 · Security	Defect	Code or a method that takes advantage of a vulnerability.
B4 · Shipping	Part	A switch that turns a feature on or off without a new deploy.
B4 · Shipping	Status	A new system doing everything the old one did.
B1 · The stack	Part	A structure of ready-made code that shapes how an app is built, such as React or Django. Two meanings: see Part C.
B1 · The stack	Part	The part users see and touch, in a browser or app.
B1 · The stack	Part	Both front end and back end.
B2 · Code and data	Part	A named block of code that does one job.
B6 · Security	Part	The government’s approved arrangement for running agency systems on commercial cloud.
B6 · Security	Part	The European Union’s data protection law.
B3 · Version control	Part	The most widely used version control system.
B3 · Version control	Part	Websites that host Git repositories and the reviews around them.
B4 · Shipping	Status	All automated checks passed, or at least one failed.
B2 · Code and data	Defect	A value written directly into the code instead of set in configuration.
B6 · Security	Part	Turning data such as a password into a fixed code that can’t be reversed.
B4 · Shipping	Stage	An urgent fix released outside the normal schedule, and a small fix in general.
B5 · Web and APIs	Part	The three languages of the web page: structure, appearance and behaviour.
B5 · Web and APIs	Part	The protocol for sending web pages and API calls. HTTPS is the encrypted version.
B5 · Web and APIs	Stage	Internationalisation, building software so it can support any language, and localisation, adapting it for one. The numbers count the letters in between.
B2 · Code and data	Part	A unique identifier for a record. A UUID is a long random one.
A5 · Readiness	Judging	Written the way the language’s community expects.
B5 · Web and APIs	Part	A web page displayed inside another page.
B6 · Security	Part	The Singapore Government’s instruction manual for managing ICT and smart systems, including security and data policies.
B5 · Web and APIs	Part	A working connection between two systems.
B4 · Shipping	Stage	A test that parts work together correctly.
A4 · Safe and open	Judging	How well a system exchanges data with others.
B2 · Code and data	Part	A plain-text format for structured data, the common language of APIs.
B1 · The stack	Part	A system for running and scaling many containers. The 8 counts the letters in between.
A1 · Speed and scale	Judging	The delay between an action and its response.
B6 · Security	Part	Giving each person or system only the access it needs.
B1 · The stack	Status	An old system still in use, often hard to change.
B1 · The stack	Part	Reusable code a program calls for one job, such as dates or charts.
B4 · Shipping	Part	A tool that flags style problems and likely errors in code.
B5 · Web and APIs	Part	A platform for delivering courses, assignments and grades.
B4 · Shipping	Stage	Testing behaviour under expected heavy use, or beyond it until it breaks.
B4 · Shipping	Part	The engineer’s own machine, and the shared development environment.
B1 · The stack	Part	Building apps with visual tools and little or no hand-written code.
B5 · Web and APIs	Part	A 1EdTech standard for launching external tools inside an LMS with sign-in and grades passed across.
B4 · Shipping	Status	A version supported for years, and one that gets no more fixes.
B2 · Code and data	Defect	An unexplained number in code whose meaning only the author knows.
B3 · Version control	Part	The primary branch: the code that counts.
A3 · Change	Judging	How easily the code can be changed and fixed later.
B6 · Security	Defect	Harmful software, and the kind that locks data until a ransom is paid.
B3 · Version control	Stage	Joining a branch’s changes into another branch, usually main.
B3 · Version control	Defect	Two changes to the same lines that the system can’t combine on its own.
B3 · Version control	Status	The change is in the main code. Not necessarily live: see Part C.
B6 · Security	Part	Signing in with a second proof, such as a code on your phone.
B1 · The stack	Part	An application split into many small services, each deployed on its own.
B1 · The stack	Part	Software that connects other systems and passes data between them.
B2 · Code and data	Stage	Moving data or a schema to a new structure or system. Two meanings: see Part C.
B4 · Shipping	Part	Fake stand-ins for real parts of a system, used so a test can run in isolation.
B2 · Code and data	Part	A self-contained file or unit of code. Two meanings: see Part C.
B1 · The stack	Part	One large application where all parts are deployed together.
B3 · Version control	Part	One repository holding many projects.
B1 · The stack	Part	An app installed for one device type, or one that runs in a browser.
B5 · Web and APIs	Part	A standard that lets one app access another on your behalf without your password.
A2 · Staying up	Judging	How well the team can see what the system is doing from its logs and metrics.
B1 · The stack	Part	Software run on an organisation’s own servers.
B5 · Web and APIs	Part	A 1EdTech standard for exchanging class lists, enrolments and grades.
B1 · The stack	Part	Code anyone may use and inspect, or code owned and licensed by a company.
B1 · The stack	Part	The base software of a device: Windows, macOS, iOS, Android.
A5 · Readiness	Judging	Built for problems that don’t exist yet.
B2 · Code and data	Part	A bundle of shared code, and the tool that installs it, such as npm or pip.
B6 · Security	Part	Singapore’s main data protection law for private-sector organisations. Public agencies follow separate government rules.
B6 · Security	Stage	Authorised, simulated attacks to find weaknesses.
A1 · Speed and scale	Judging	How fast and efficiently the software does its work.
B6 · Security	Defect	Tricking people into giving away access or data.
B6 · Security	Part	Data that can identify a person: names, IDs, photos, contact details.
B4 · Shipping	Part	The automated sequence of build, test and deploy steps. Two meanings: see Part C.
A5 · Readiness	Judging	Fit to run for real users: tested, monitored and secure.
B4 · Shipping	Part	The live system real users rely on. Two meanings: see Part C.
B1 · The stack	Part	The language code is written in: Python, JavaScript, Java.
B3 · Version control	Part	A proposed change, opened for review before it joins the main code.
B3 · Version control	Stage	Sending your commits to the shared repository, or fetching others’
B1 · The stack	Part	A web app that can be installed and work partly offline.
B4 · Shipping	Stage	Systematic testing to find defects before users do. Also the team that does it.
B5 · Web and APIs	Part	A 1EdTech standard for exchanging assessment items and tests.
B2 · Code and data	Part	A request to a database for specific data.
B5 · Web and APIs	Measure	A cap on how many requests a caller may make in a period.
B6 · Security	Part	Permissions granted by role, such as teacher, student or admin.
A3 · Change	Judging	How easily another engineer can understand the code.
B3 · Version control	Part	The front-page document of a repository: what it is and how to use it.
B3 · Version control	Stage	Replaying your changes on top of the latest code to keep history tidy.
B2 · Code and data	Stage	Restructuring code without changing what it does, to make it easier to read and change.
B2 · Code and data	Part	A pattern for matching text, such as a valid email address.
B4 · Shipping	Stage	A test that old features still work after a change.
B4 · Shipping	Stage	Making a feature available to users. Can happen after deploy, through a flag.
A2 · Staying up	Judging	How consistently the system works as expected.
B3 · Version control	Part	The stored home of a project’s code and its full history.
B5 · Web and APIs	Part	A message asking a server for something, and its reply.
A2 · Staying up	Judging	The ability to keep working when a part fails.
B5 · Web and APIs	Part	Two common styles of designing an API.
B6 · Security	Measure	How long data may be kept before it must be deleted.
B3 · Version control	Stage	Undoing a change with a new commit that reverses it.
B3 · Version control	Role	The person asked to review a change, and the person whose approval it needs.
A2 · Staying up	Judging	Holds up under unexpected input, or breaks easily.
B4 · Shipping	Stage	Returning to the previous version after a bad release.
B4 · Shipping	Stage	Releasing gradually: some users, then more, then all.
B1 · The stack	Part	The environment that actually runs the code, such as Node.js.
B1 · The stack	Part	Software, platform or infrastructure “as a service”: how much the provider runs for you.
B4 · Shipping	Part	A safe, isolated environment for trying things without consequences.
A1 · Speed and scale	Judging	How well a system copes as users or data grow.
B2 · Code and data	Part	The defined structure of data: which fields exist and what they hold.
B5 · Web and APIs	Part	An older standard for packaging e-learning content so any LMS can run it and record completion.
B2 · Code and data	Part	A short program that automates a task.
B1 · The stack	Part	A bundle of tools and libraries for building on a platform.
B6 · Security	Part	A password, key or token that grants access.
A4 · Safe and open	Judging	Protection against misuse, attack and data loss.
B2 · Code and data	Part	Fake data used to fill a system for development and testing.
B5 · Web and APIs	Part	Markup that describes what content is, such as a heading or a button, and attributes that make custom widgets accessible.
B4 · Shipping	Measure	Version numbers as major.minor.patch, such as 2.4.1. A major change can break things (Preston-Werner, n.d.)
B5 · Web and APIs	Part	Making pages easy for search engines to find and rank.
B1 · The stack	Part	Code run by the cloud provider on demand, with no server to manage.
B4 · Shipping	Stage	Informal: to release.
B6 · Security	Part	Singapore’s national digital identity for signing in to government services.
B5 · Web and APIs	Part	The system of record for enrolment, classes and student details.
B4 · Shipping	Stage	A quick check that the most basic functions work at all.
B2 · Code and data	Part	The human-written instructions of a program, and the whole body of it.
B5 · Web and APIs	Part	A web app that updates in place instead of loading new pages.
B2 · Code and data	Part	The standard language for querying table-based databases, and databases that store data other ways.
B6 · Security	Part	One sign-in that opens many systems.
B1 · The stack	Part	The set of technologies a product is built on.
B4 · Shipping	Part	A near-copy of production for final checks before release.
B3 · Version control	Defect	A branch left so long it no longer fits the main code.
B5 · Web and APIs	Measure	A server’s numbered reply: 200 OK, 301 moved, 403 forbidden, 404 not found, 429 too many requests, 500 server error, 503 unavailable.
B2 · Code and data	Part	A set of records, one record and one item within it.
B3 · Version control	Part	A named marker on one point in history, usually a release version.
A5 · Readiness	Judging	The future cost of shortcuts taken now (Cunningham, 1992).
B4 · Shipping	Measure	The share of code exercised by automated tests.
A3 · Change	Judging	How easily the code can be checked automatically.
B6 · Security	Stage	A structured look at who might attack a system, how and what to protect.
A1 · Speed and scale	Judging	How much work a system handles in a given time.
B2 · Code and data	Measure	A recorded date and time, the world reference time, and the standard way to write dates (2026-10-02)
B6 · Security	Part	The encryption behind HTTPS. SSL is the older name, still widely used.
B5 · Web and APIs	Part	JavaScript with added type checking, which catches errors earlier.
B4 · Shipping	Stage	Testing by real users or business owners to confirm the software meets their needs.
B2 · Code and data	Part	The standard that covers every writing system, and its most common encoding.
B4 · Shipping	Stage	An automated test of one small piece of code on its own.
B5 · Web and APIs	Part	A web address.
B6 · Security	Stage	The combined security testing required before systems go live.
B2 · Code and data	Part	A named container for a value that can change.
B1 · The stack	Defect	Dependence on one supplier that makes switching costly.
B3 · Version control	Part	A system that records every change to code, who made it and why.
B1 · The stack	Part	A simulated computer running inside a real one.
B6 · Security	Defect	A weakness that could be exploited.
B5 · Web and APIs	Part	An automatic message one system sends another when something happens.
B5 · Web and APIs	Part	A standard for recording learning activity as statements, and the store that holds them.
B6 · Security	Defect	A vulnerability attackers know about before a fix exists.

Appendix B

The defects, by family

The 11 defects in this volume, in family order, with where each one turns up.

Defect	Family	What it is	Where you’ll meet it
Vendor lock-in	B1 · The stack	Dependence on one supplier that makes switching costly.	Procurement reviews.
Hardcoded	B2 · Code and data	A value written directly into the code instead of set in configuration.	“The term dates are hardcoded”
Magic number	B2 · Code and data	An unexplained number in code whose meaning only the author knows.	Code reviews.
Merge conflict	B3 · Version control	Two changes to the same lines that the system can’t combine on its own.	Busy codebases.
Stale branch	B3 · Version control	A branch left so long it no longer fits the main code.	Abandoned work.
Vulnerability	B6 · Security	A weakness that could be exploited.	Security reports.
Exploit	B6 · Security	Code or a method that takes advantage of a vulnerability.	Security advisories.
Zero-day	B6 · Security	A vulnerability attackers know about before a fix exists.	Urgent patches.
Phishing, social engineering	B6 · Security	Tricking people into giving away access or data.	Staff training.
Malware, ransomware	B6 · Security	Harmful software, and the kind that locks data until a ransom is paid.	Incident reports.
Data breach	B6 · Security	Unauthorised access to or release of data.	Incident reports and notifications.

Appendix C

Words with two meanings

The seven definitions in this volume that carry two meanings. Six point to Part three, where education uses the same word. The rest carry two meanings inside engineering.

Term	Family	What it means
Framework	B1 · The stack	A structure of ready-made code that shapes how an app is built, such as React or Django. Two meanings: see Part C.
Module	B2 · Code and data	A self-contained file or unit of code. Two meanings: see Part C.
Dependency	B2 · Code and data	Outside code a project relies on. Two meanings: also a task that waits on another (B9)
Migration	B2 · Code and data	Moving data or a schema to a new structure or system. Two meanings: see Part C.
Pipeline	B4 · Shipping	The automated sequence of build, test and deploy steps. Two meanings: see Part C.
Environment	B4 · Shipping	A separate copy of the system for one purpose. Two meanings: see Part C.
Production, prod	B4 · Shipping	The live system real users rely on. Two meanings: see Part C.

Appendix F

The judging words as a checklist

Each word for judging reduces to one way of looking at a system. Extracted, in order from speed to readiness, they are a one-page review.

Word	Group	How to see it
Performance	Speed and scale	Time the slowest thing a real user does, with real data: the class of forty, not the test class of five.
Latency	Speed and scale	Count the wait between a click and the screen changing, and ask for the slow end, not the average.
Throughput	Speed and scale	Ask how many users, submissions or requests the system has handled at once, not how fast it handles one.
Scalability	Speed and scale	Ask what has to grow when the users grow: servers, licences, staff time, or nothing at all.
Reliability	Staying up	Look at the record, not the promise: how often it failed last term, and when.
Availability, uptime	Staying up	Turn the percentage into time.
Resilience, fault tolerance	Staying up	Pick one part of the system and imagine it gone.
Robust, brittle	Staying up	Feed it what real users will: an apostrophe in a surname, a name in Chinese or Tamil script, a blank field, a file twice the expected size.
Observability	Staying up	Ask what the team could see during the last incident, and how long it took to find the cause.
Maintainability	Change	Ask how long a small change takes, and who can make it.
Readability	Change	Read a short piece of the code aloud.
Testability	Change	Ask whether a piece of the system can be checked on its own, automatically, in seconds.
Complexity	Change	Ask how many parts a request passes through, and how many paths there are through the code.
Coupling	Change	Ask what else has to change when one part changes.
Cohesion	Change	Ask what a file or module is for, in one sentence.
Security	Safe and open	For every way into the system, ask two questions: who can reach this, and who should be able to?
Accessibility, a11y	Safe and open	Put the mouse away and try the main task with the keyboard alone, then with a screen reader.
Interoperability	Safe and open	List the systems this one must exchange data with, and ask how each exchange happens.
Developer experience (DX)	Safe and open	Ask an engineer outside the team to make one working call to the API, or set up the tool, from the documentation alone, and time it.
Idiomatic	Readiness	Ask an engineer who knows the language whether the code reads as that language usually does.
Over-engineered	Readiness	Ask which part of the design serves a need the users have today, and which serves one somebody imagined.
Production-ready	Readiness	Ask what happens when the demo meets real users: real data, real load, real attackers, a failure at 2 a.m.
Technical debt	Readiness	Ask whether changes are getting slower.

Appendix G

Verification register

Every cited claim in the source glossary was checked against the work it names. The items below are the corrections made and the points worth knowing.

Entry	What was checked or corrected
Counts	The rows hold 453 terms in 14 families, 48 of them defects, plus 23 words for judging and 22 false friends. Every count in this companion is generated from the rows.
Kinds outside the eight	Five rows carry a kind the companion glossaries use and this one does not define: Move (throttling, zero-shot and few-shot, vibe coding) and Format (COTS, licence models). They are shown as the nearest of the eight: Pattern for the moves and Part for the formats.
The nines	A year has 8,760 hours. At 99.9% availability the allowed downtime is 8.76 hours, which the definition rounds to about 8.8. At 99.99% it is 52.6 minutes, about 53.
Kubernetes, K8s	Eight letters stand between the K and the s, which is where the 8 comes from.
Technical debt	The metaphor is Cunningham’s, from his 1992 OOPSLA experience report on the WyCash system.
SLO, SLI, SLA, error budget	The service-level vocabulary and the error budget follow Beyer et al. (2016). The SLA is the contract; the SLO is the internal target; the SLI is the measurement.
Strangler fig pattern	Fowler’s article was posted on 29 June 2004 as “StranglerApplication” and renamed “Strangler Fig Application” in April 2019. Its text now lives at a new address; the old address carries a separate 2024 article, “Strangler Fig”. The reference list points to the 2004 text.
Conway’s law	Conway (1968), in Datamation, April 1968. Conway’s own page confirms the month; the volume, issue and pages follow the usual citation, since secondary sources disagree on the issue number. The inverse Conway manoeuvre was coined later, by LeRoy and Simons of ThoughtWorks in 2010, and is left uncited as the source leaves it.
Walking skeleton, tracer bullet	Cockburn (2004) for the walking skeleton; Hunt and Thomas (1999) for the tracer bullet, DRY and rubber duck debugging.
Big ball of mud, circuit breaker	Foote and Yoder (1997) at PLoP ’97; Nygard (2007) for the circuit breaker.
Brooks’s law, second-system effect	Both are from Brooks (1975).
Premature optimisation	Knuth (1974): “premature optimization is the root of all evil”, from a passage arguing for measuring before optimising.
Domain-driven design	Anti-corruption layer, bounded context and ubiquitous language are all from Evans (2003).
Team types	Stream-aligned, platform, enabling and complicated-subsystem are the four team types of Skelton and Pais (2019).
Rehost, replatform, refactor…	The six options are the migration strategies popularised by AWS. Some later versions add a seventh, relocate.
PDPA, IM8, VAPT	The Personal Data Protection Act 2012 excludes public agencies, which follow the Public Sector (Governance) Act 2018 and the government’s instruction manual, as the definition says. IM8’s full name is the Instruction Manual for Infocomm Technology and Smart Systems (ICT&SS) Management. IM8 is not public, so the requirement for VAPT before go-live could not be checked against a published source.
Learning-technology standards	LTI, QTI and OneRoster are 1EdTech (formerly IMS Global) standards. SCORM and xAPI come from ADL, the US Advanced Distributed Learning initiative; the source does not attribute them, and nor does this companion.
Data and AI terms	Current at October 2026, as the family’s introduction says. Re-check agent, evals, open weights, context window and RAG before relying on them.
Two points left as written	React, named under Framework, describes itself as a library; Django is a framework. Brooks’s law sits with the anti-patterns but keeps the kind the source gives it, Pattern, since it names an observation rather than a fault.
Figures	Every drawing is schematic: invented systems, code, names and numbers, not a real product, team or incident.

Source trail

References

The works the source glossary cites, in its own list. Most of the terms are trade vocabulary with no single source. Those that rest on a published work name it in the definition.

Beyer, B., Jones, C., Petoff, J., & Murphy, N. R. (Eds.). (2016). Site reliability engineering: How Google runs production systems. O’Reilly Media. https://sre.google/sre-book/table-of-contents/
Brooks, F. P. (1975). The mythical man-month: Essays on software engineering. Addison-Wesley.
Cockburn, A. (2004). Crystal clear: A human-powered methodology for small teams. Addison-Wesley.
Conway, M. E. (1968). How do committees invent? Datamation, 14(4), 28–31. https://www.melconway.com/Home/Committees_Paper.html
Cunningham, W. (1992). The WyCash portfolio management system. In Addendum to the proceedings on object-oriented programming systems, languages, and applications (pp. 29–30). ACM. https://doi.org/10.1145/157709.157715
Evans, E. (2003). Domain-driven design: Tackling complexity in the heart of software. Addison-Wesley.
Foote, B., & Yoder, J. (1997, September). Big ball of mud [Paper presentation]. Fourth Conference on Pattern Languages of Programs (PLoP ’97), Monticello, IL, United States. http://www.laputan.org/mud/
Fowler, M. (2004, June 29). Strangler fig application. https://martinfowler.com/bliki/OriginalStranglerFigApplication.html
Hunt, A., & Thomas, D. (1999). The pragmatic programmer: From journeyman to master. Addison-Wesley.
Knuth, D. E. (1974). Structured programming with go to statements. Computing Surveys, 6(4), 261–301. https://doi.org/10.1145/356635.356640
Nygard, M. T. (2007). Release it! Design and deploy production-ready software. Pragmatic Bookshelf.
Preston-Werner, T. (n.d.). Semantic versioning 2.0.0. https://semver.org
Skelton, M., & Pais, M. (2019). Team topologies: Organizing business and technology teams for fast flow. IT Revolution.