ABOUT THIS WORK
What software owes its reader
A machine can speak with exquisite manners and still leave its reader in difficulty. What matters is whether its account of the event is true, complete enough for the decision at hand, and delivered while the reader can still act on it.
This essay works through that obligation using the messages collected in The Courteous Machine. Every specimen below is quoted from the project's catalog, and its caption gives the record it came from, so you can open the full entry and its editorial note in the phrasebook.
The names, addresses, amounts, dates, and systems in the specimens are illustrative. Each one shows wording under stated conditions. None of them reports the state of a real account, payment, or service. The prose around them explains what an implementation would have to know before sending such a message at all.
A00The reply that never arrived
A refund request leaves an application. The connection then closes without an acknowledgement. A conventional interface may show an error, because it has no successful response to show instead. Yet the absence of a reply establishes only that the application lacks a reply. The payment provider may have accepted the request, may have rejected it, or may never have received it. Those three possibilities lead a person about to press Retry to three different places.
The catalog opens, for this argument, with an unusually plain admission. It gives the attempted amount and the order it belongs to, names the response that never came, and declines to record a result it cannot establish. Then it points the reader somewhere the true state can be checked.
Case 01. An unconfirmed refund
I cannot truthfully confirm whether the refund was issued. Refund GBP 142.00 against order SO-61250 Submitted 27 September 2026 at 14:02:11 BST Provider Northwind Payments, merchant MER-20418 Response none; the connection closed after 45 seconds The provider may have accepted it, or may never have received it. I will not record it as done, and I will not record it as failed. Check Payments > Refunds in the Northwind dashboard before issuing another, as a second submission would refund twice. The idempotency key sent with the attempt was rf_4471; use it when searching.
The restraint does more work here than the phrasing. The message does not call an unknown outcome a failure in order to keep the interface tidy. It does not ask the reader to repeat a financial operation because the application would prefer a simpler story. The idempotency key ties this uncertain attempt to the provider's record, but only if the application really sent that key and somebody can really search for it. Notice also what the notice does not close off. It names acceptance and non-receipt as possibilities, and a provider rejection stays possible too, until an authoritative status check settles the matter. None of this can be written at all unless the interface keeps the attempted amount and the provider's response, or its absence, long enough to report them.
That is the governing proposition here. A software message is a short account of an event, addressed to someone who may have to make a decision. Its manners decide how the account is received. Its observed facts, its boundaries, and its next action decide whether the account can be trusted. Long prose earns its place when an event has several consequential states. A routine field correction may need no more than a sentence beside the field.
B00A borrowed manner, a different correspondent
The premise owes an explicit debt to Bespoke: A Programming Language for People Who Say Please by Christian Hofstede-Kuhn, published on the Larvitz Blog. Bespoke imagines source code that addresses a compiler and a runtime with elaborate consideration. It makes an entertaining point about the violent verbs of programming by replacing commands with petitions, acknowledgements, and dignified accounts of regrettable circumstances.
The Courteous Machine carries that voice into a different exchange. Here the addressee is a person using software, perhaps in the middle of work that cannot be repeated cheaply. The fictional clerk may call a failure a regrettable circumstance. It must still name the affected record, the observed code, the boundary the operation reached, and a safe next step. The voice is an artistic choice. Accuracy is not a matter of style.
The difference shows most clearly when a message has nothing to apologize for. A completed export can be announced with pleasure. A search that ran and found no matches can say so without pretending it failed. A scheduled withdrawal can offer notice rather than regret for an event that has not happened yet. Software has a wider range of things to say than a collection of quaint error apologies, and the tone should follow the event rather than precede it.
The project keeps four registers: light, formal, ceremonial, and theatrical. They describe language, not degrees of technical confidence. A theatrical sentence must meet the same standard of factual support as a plain one. The most dramatic part of a message should never be its least verified claim.
C00First establish the state
Before choosing an opening, decide which event the system has actually observed. A request can be rejected during validation. It can be accepted for processing, or waiting in a queue, or running. It can finish for every item, or for only some of them. It can turn out to be already satisfied, cancelled in part, or left with an outcome that some other service knows and this one does not. A screen should not collapse all of that into one cheerful word. A response from one component also says little about another component unless the application checks the boundary between them.
| Observed state | What the message may say | What it must not assume |
|---|---|---|
| Rejected before execution | The input or policy stopped this attempt, if the rejection point is known. | That other saved work disappeared. |
| Accepted or queued | The request was received, and where its status can be found. | That processing began or a result exists. |
| Running | Measured progress and the effect on available features. | A completion time the measurements cannot support. |
| Completed | The verified output or effect, and any remaining action. | That every downstream delivery is finished. |
| Partly completed | The successful and unsuccessful units, separately. | That repeating the whole batch is harmless. |
| Already satisfied | The requested condition was checked and no change was made. | That a new change occurred. |
| Unknown | What was attempted, which acknowledgement is missing, and how to check. | Either success or failure, from silence alone. |
These rows are an editorial aid rather than a new protocol. A real system may have more states than this, and may know less than the table assumes. The writer's job is to follow the actual state machine, and the evidence available at the moment of display. A phrasebook supplies language for an observed condition. It cannot discover that condition on the application's behalf.
Tense does real work here. "Was submitted" names a past event. "Is processing" asserts a present condition and needs current information to stand up. "Will be sent" promises future behavior. "Was delivered" needs evidence from the delivery system, not merely from the service that sent the thing. A considerate sentence tells the reader when it crosses from one kind of statement to another.
D00The parts of an account
Six questions test a message. What event happened? Which object or operation does it concern? What is the present state, including anything unknown? What consequence matters to this reader? What action is available now? What reference will let the matter be found again? Few messages need all six answers on screen. The point is to choose deliberately which answers the moment requires.
Consider a request accepted for background processing. The acknowledgement is genuine, and it is narrower than a result. The catalog gives the job a name, states that processing has not started, and points to a durable status record rather than asking the reader to keep a page open.
Case 02. A request received, with no output yet
Your request has reached the queue; it has not yet reached its conclusion. Job 5c40be91 was accepted at 14:02:11 BST on 27 September 2026. Processing has not started, and no output file is available yet. Input quarter-close.zip, 2.8 GB Position 31 of 47 Workers 12 Estimate starts at about 15:40 BST You may close this page. The job's status and eventual output will remain available under Activity, and an e-mail will be sent to operations@example.com when the file is ready.
The opening, "Your request has reached the queue," is more exact than a generic success toast. The sentence after it removes the usual misunderstanding. There is no output file yet. The queue position and the estimate are worth printing only if they come from a real scheduling view, and the promised Activity record and email have to exist. An application that cannot offer those channels must edit the sentence rather than copy it intact.
Reference details have a purpose too. A job ID connects the notice to a status view or a support conversation. A filename connects it to the reader's own work. A technical code may belong in a details region for an administrator, where it need not displace the ordinary explanation. A field-level correction seldom needs a full docket of timestamps. A delayed export may well need its expiry date, file size, and download location. Completeness is relative to the decision the reader has to make.
A message is therefore part of an interface, not a literary paragraph floating above one. If it says "Select Download," a Download control should exist. If it says a report is under Activity, that route should be reachable and named that way. If there is genuinely nothing to do, "No action is required" is a useful conclusion. It is not a consolation phrase to append to work whose state is still unsettled.
E00Three reasons to ask for input
An invalid value, an ambiguous value, and a choice of policy are three different situations. A field-specific explanation usually settles the first. The second has two valid meanings and needs disambiguating. The third asks for an instruction the software has no authority to invent. Treating all three as "bad input" hides the decision from the person who owns it.
The date in the next specimen does not exist. The message identifies the field and the entered value, keeps the rest of the quotation, and offers a correction without deciding that the reader meant the last day of February.
Case 03. An impossible date with the rest of the form retained
I beg your pardon, but the date provided does not correspond to a day recognised by the calendar. Field Policy start date Entered 2026-02-30 Accepted no Quotation Q-78421, saved 27 September 2026 at 14:18 BST February 2026 ends on the 28th. The quotation has kept your other answers, including the vehicle and the no-claims years, and only this field is waiting. If the last day of February was intended, enter 2026-02-28; otherwise enter the intended date, then select Continue.
That sentence about kept answers has to come from the form's actual persistence behavior. It matters, because otherwise the reader may re-enter a long application. GOV.UK's error-message guidance recommends keeping entered answers when validation fails, and placing specific errors with their fields. W3C's error-identification criterion requires an automatically detected input error to identify the affected item and describe the problem in text. An elegant apology satisfies neither recommendation on its own.
An impossible date has a simple correction. The next specimen is harder, because its local time happens twice. A scheduler cannot know which occurrence the reader intended when the clocks move back. The message puts both corresponding UTC instants beside the schedule and states that nothing has been saved.
Case 04. A local time that occurs twice
The clock supplies this time twice, so one further detail would be helpful. In Europe/London, the local time 2026-10-25 01:30 occurs twice when the clocks move back. It could mean 2026-10-25 00:30 UTC or 2026-10-25 01:30 UTC. Schedule SCH-7714, "Nightly reconciliation" Entered 01:30, daily First 01:30 BST, UTC+01:00, before the clocks change Second 01:30 GMT, UTC+00:00, after the clocks change Affected one occurrence per year Please select the intended occurrence. The schedule has not been saved. If either is acceptable, choosing the first means the job runs before the clocks change.
Here the courtesy is a request for one more detail rather than a euphemism for a parser failure. The example has to be generated from the selected time zone's rules. A fixed assumption about daylight saving would reintroduce the very ambiguity the message is trying to resolve. Its final sentence makes the consequence of the first choice explicit.
Some missing input is a policy rather than a value. When an import finds existing identifiers, "continue" means nothing until the reader decides whether to keep, replace, or inspect the matches. The counts in the next specimen show how large that decision is, and the message states that validation is complete while the import has not begun.
Case 05. A conflict policy the software cannot choose
There is a decision here that the software should not make on your behalf. The import contains 42 records whose identifiers already exist. Continuing requires a policy for those matches: keep the existing records, replace them, or review each conflict. Validation imp_20260927_1018 File customers-october.csv, 4,102 rows New 4,060 records Matching 42 records, of which 31 differ in at least one field Identical 11 matching records contain no field differences Conflicts listed in customers-october-conflicts.csv Please choose a conflict policy. Validation is complete; the import has not started, so no record has been changed either way.
These three messages ask for three different actions: edit the date, select the occurrence, choose a conflict policy. A polite register must not weaken a mandatory instruction. In its own setting, GOV.UK guidance advises against "please" in a required-field error, because it can make the field sound optional. This phrasebook deliberately offers a more mannered voice. The action itself still has to stay direct, and visibly attached to the right field or control.
F00Technical, permissive, or real
A service can reject an upload. A token can lack the required scope. A product can lack the requested capability altogether. These conditions are not interchangeable. The first asks for a smaller payload or another transfer route. The second asks for different authority. The third asks the reader whether an available approximation will do. An application should not turn a service failure into a personal rebuke, or imply that a missing feature can be fixed by trying again.
In the upload example, the technical status arrives with an ordinary-language explanation beside it. The file size and the server limit make the failure concrete, and a desktop uploader offers a different route. The claim that nothing partial was stored rests on the server refusing the body before reading it, not on the mere appearance of HTTP 413.
Case 06. A payload the server declined before storage
Pardon the interruption. The upload could not be completed because the server returned HTTP 413, meaning the submitted body exceeded its configured limit. File: site-backup-2026-09.tar Size: 6.4 GB Server limit: 2 GB Please upload a smaller file or use the desktop uploader, which sends in 100 MB parts. Attempted: 27 September 2026 at 12:48:16 BST Technical status: HTTP 413 Payload Too Large Reference: 8f1c7d2a The request was refused before the body was read, so nothing partial was stored and no storage has been consumed.
The permission example takes equal care with scope. A token that can read one organization is not wholly invalid because it cannot read another. The message names the authorized organization and the requested one, states that no content came back from the requested one, and offers two legitimate routes forward.
Case 07. A valid token outside its assigned scope
Your permission is valid, but its reach stops short of this request. The current token permits reading repositories in northgate-mills. The requested repository belongs to meridian-labs, which is outside that token's authorised scope. Token "Deploy Reader", fingerprint ending 4471 Created 2 August 2026; last used 09:12 BST today Scopes repo:read on northgate-mills Requested meridian-labs/pricing-engine Denied clone at 09:13:04 BST on 27 September 2026 No content from meridian-labs/pricing-engine was retrieved. Please select a token with access to the requested organisation or choose a repository within the current scope. The token remains valid for everything it was issued for and has not been revoked.
Some sensible requests lie outside what the product can express at all. Such a request deserves recognition without the fiction that a feature is "temporarily unavailable" when it has never existed. The calendar example refuses to guess that the 28th is close enough to the last working day. It proposes an approximation and lets the reader judge whether that different schedule serves the original purpose.
Case 08. A reasonable request beyond the service's capabilities
The request is a perfectly sensible one; it is simply not among the
things this service is able to do.
Requested schedule a report to run on the last working day of each
month
Supported a fixed day of the month, a fixed weekday, or a fixed
interval in days
There is no arrangement of the present options that expresses "last
working day", and rather than approximate it with the 28th and hope,
nothing has been scheduled.
The nearest available arrangement is the last day of each month, with
delivery on the following Monday when it falls at a weekend. Select
Use nearest arrangement to set that up, or Request this feature to
record the original intention.
Reference: SCH-FEATURE-118
The proposed arrangement of calendar day plus following Monday does not calculate the last working day. Public holidays and local business calendars can make that substitution wrong even when the weekday looks right. An implementation must either evaluate the relevant calendar or present this as an explicitly different rule for the reader to approve.
A message can be humane without flattering the reader or blaming them. It should say who can change the situation. A permission request may have a steward. A technical limit may have a supported alternative route. A missing feature may deserve a request to the product team. The remedy has to be a real control or a real process rather than a courteous fiction.
G00The dangerous verb is retry
A retry is harmless only under conditions the application actually enforces. The first attempt may have reached another system while its response was lost on the way back. A second attempt might create a second shipment, a second refund, or a second notification. In those cases the next action is a status check rather than another submission.
The shipment specimen keeps four things apart: the request sent to the carrier, the lost connection, the unknown outcome, and the cost of a duplicate. It also warns that the carrier's list can lag. That warning stops a momentarily empty view from becoming false proof of failure.
Case 09. A shipment whose creation remains uncertain
Before we trouble the service a second time, please verify whether the first request has already completed. Request create shipment for order SO-55310 Carrier NorthStar Freight Sent 27 September 2026 at 09:14:22 BST Waited 30 s, then the connection was lost Outcome unknown Key idempotency key ship_55310_0927 A shipment may or may not exist. No second shipment request has been sent. Creating another would put two labels on one order and charge carriage twice. The shipment list for this order is below and is read directly from the carrier, though it may lag by a few minutes. If no shipment appears, ask NorthStar Freight to search for idempotency key ship_55310_0927 before repeating the request.
An idempotency key can help a service recognize a retry, but the contract belongs to the particular API. Stripe's API documentation describes one implementation. Stripe associates a key with the result of an executing request, and rejects a later reuse when the parameters differ. The catalog's next case illustrates that second rule. The key refers to an order for three units, and a later request for five units is a new instruction, however similar its identifier looks.
Case 10. A reused key with changed request contents
This reference already belongs to a different set of instructions. Request key ord_4471a was previously submitted with quantity 3. The new submission uses the same key with quantity 5. A retry must preserve the original request contents. Original ORD-730184, quantity 3, submitted 09:14:02 BST Status accepted for fulfilment; not yet dispatched New quantity 5, submitted 09:14:41 BST Action the new submission was refused before processing Please restore quantity 3 if you are retrying the original operation. If you intend a separate operation, check the original at Orders > ORD-730184 first, then submit the new request with a new key.
The operational question is therefore sharper than "Can the user retry?" Which first operation reached which boundary, carrying which contents and which key, and what does the receiving service guarantee? No wording can confer idempotency on an operation that lacks it. Where no duplicate protection and no authoritative status exist, the message should say that a person must check before the next consequential request.
A database rollback brings a related temptation. The database may reverse a local transaction cleanly while an email, a webhook, or some other external effect has already crossed into another service. The next specimen reports both facts and leaves delivery unconfirmed.
Case 11. A rollback with an external consequence still outstanding
The database has been put back in order. One external consequence
remains.
The database transaction was rolled back successfully. However,
notification ntf_88204 had already been accepted by the messaging
service, and the rollback did not withdraw it.
Rolled back order SO-55123 and its 4 lines; no record was
created
Not withdrawn "Your order has been received", accepted by msg-eu-2
at 09:41:18 BST for a.whitfield@example.org;
delivery not yet confirmed
Please review that notification before retrying the operation. A
retry could give the customer two confirmations for an order that
does not yet exist, if the first is delivered.
"Rolled back" is thus a claim with a scope. It may describe database rows and say nothing about an email already accepted elsewhere. The reader needs the surviving effect, its current delivery state, and the risk of another attempt. Where the system cannot observe all three, it should label what remains unknown rather than seal the letter with an all-clear.
H00Success has more than one shape
Success does not always mean a new record was written. A request can find the desired state already present. A background job can finish and leave a file to collect. A batch can produce usable results while rejecting some of its units. These outcomes deserve separate language, because they imply different next actions.
The first example confirms membership in a group and reports that no change was necessary. From the reader's side it is a success. From the system's side it is a verified no-op. Saying "added" would misdescribe an account that was already a member.
Case 12. The desired state was already true
The requested state had already been achieved. I therefore took the liberty of doing nothing further. Account m.delgado was submitted for addition to the group Release Managers, of which it has been a member since 4 March 2024. Request received 27 September 2026 at 12:18 UTC Submitted by deployment request DR-9184 Membership is unchanged at 11 accounts. Nothing further is required. Reference: IAM-0442
The second example describes a finished export. The object, filter, row count, format, size, availability period, and collection step together make the outcome usable. The claim that no row was omitted is unusually strong. A product must check that claim rather than borrow the phrase for reassurance.
Case 13. A completed export with a collection window
The customer export you asked for is finished and the result is ready to collect. Export EXP-90218, all customers with orders since 1 January 2026 Rows 402,558 File customers-2026-09-27.csv, 84 MB, UTF-8 Finished 27 September 2026 at 14:26 BST, after 11 minutes Available until 4 October 2026, then deleted The file is complete; no row was omitted and no filter was applied beyond the one you chose. Select Download to collect it. It can be downloaded more than once while it remains available.
The third example is deliberately untidy. Most of the images were resized, while eighteen source files turned out to be PDFs and could not be processed as images at all. The message names both sets, keeps the originals, and offers a retry limited to the unfinished subset. Calling the whole batch complete would misstate the result, and repeating all 430 would duplicate work that does not need repeating.
Case 14. A batch that partly succeeded
412 items finished; 18 could not be processed. Review the list below to retry only the remaining items. Batch IMG-430-0927, resize product photographs Finished 412 of 430 Failed 18, all because the source file is a PDF, not an image Accepted JPEG or PNG, up to 25 MB each datasheet-va40.pdf datasheet-va55.pdf datasheet-va60.pdf fitting-guide-a.pdf fitting-guide-b.pdf ... and 13 more, listed in full below The 412 are in place and need no repeating. The 18 originals are untouched and their product pages still show the previous photographs. Replace the 18 PDFs with JPEG or PNG files, then select "Retry remaining". Retrying all 430 would redo work that is already correct. Reference: IMG-430-0927
A no-op, a completed output, and a partial success are not three ceremonial synonyms. They are three different accounts of system state. A useful positive message gives evidence of what is ready, where to find it, whether the reader must act, and whether any part remains unresolved. Courtesy can celebrate a result. It cannot enlarge one.
I00Information before anything goes wrong
A notice can be valuable precisely because it arrives before the event. Maintenance, deprecation, a retention deletion, and an unfamiliar sign-in are not four variants of one warning. They carry different deadlines and demand different decisions. The first asks when work will be interrupted. The second asks how to migrate. The third asks whether to preserve records before a cutoff. The fourth asks whether a recorded action was authorized.
The maintenance notice separates the affected reporting functions from the main application and the API. It also says what will happen to scheduled reports inside the window. The time zone is part of the message rather than a detail left to the reader's guesswork.
Case 15. A maintenance window with a bounded impact
The reporting service will be unavailable from 02:00 to 05:00 UTC on Saturday 3 October 2026 for scheduled maintenance. Please save your work before then. Affects scheduled reports, exports and the dashboard Unaffected the main application and the API Duration 3 hours Maintenance CHG-8042 Reports due in that window will be queued rather than cancelled and will run when service returns, expected at 05:00 UTC. Exports started before 01:45 UTC will be allowed to finish. This is the only notice that will be sent until the day before. Status updates: status.example.com/CHG-8042.
That notice promises a particular reminder cadence. Such wording is safe only where the notification schedule is configured and monitored to match it. A live product should give the next actual reminder date, or drop the exclusive promise if its timing may change.
The deprecation notice works on a longer horizon. It names current usage, the affected endpoints, the replacement's behavior, the withdrawal date, and the response old calls will receive afterwards. The migration path is useful here precisely because the notice arrives while the old API still works.
Case 16. A planned API withdrawal while migration is possible
The v1 reporting API will be withdrawn on 31 March 2027. The v2
reporting API performs the same work, and existing v1 API keys will
continue to function until then.
Your usage 18,402 v1 calls in the last 30 days, from 3 keys
Endpoints /v1/reports/monthly, /v1/reports/custom
Replacement /v2/reports, which accepts the same parameters and
returns the same fields with ISO 8601 dates
Withdrawn 31 March 2027, 23:59 UTC
Nothing has changed today, and no call has been refused. After the
withdrawal date v1 calls will return HTTP 410.
The migration notes are at developers.example.com/v2-migration. A
six-month extension can be requested until 31 December 2026.
Reference: API-V1-SUNSET
A retention notice carries a different urgency. The affected conversations and their attachments will be deleted under a stated policy. The legal-hold exclusions and the absence of recovery belong beside the deadline. The route to preserving anything must be open before the deletion happens.
Case 17. A deletion scheduled by policy, announced in advance
Under the retention policy, 14,208 support conversations are due to be deleted on 1 November 2026. Nothing has been deleted yet. Covers conversations closed before 1 November 2023 Policy three years from closure, set by your administrator Excluded 412 conversations on legal hold, which are never deleted Recovery none after deletion Attachments within those conversations are deleted with them. Exporting them afterwards will not be possible. If any should be kept, apply a legal hold or export them before 1 November 2026 from Settings > Retention. Reference: RET-20261101
These three notices should never collapse into "something is changing soon." They explain what is changing, when, for whom, and how the reader may prepare. If a date moves, the message has to move with it. A decorative reminder carrying the wrong date is worse than silence.
Security information calls for another kind of restraint. A successful sign-in from a new device is an observation, not proof of an intruder. The message gives the time, the device, an estimated network location, and the live session state, then branches. Nothing to do if the reader recognizes it. Concrete session and password controls if not.
Case 18. A recorded sign-in without an invented accusation
A sign-in was recorded from a device this account has not used before. If it was you, nothing need be done. Account r.okafor@example.org When 27 September 2026 at 21:14 BST Device Firefox 142 on Windows, not seen before on this account Network 92.0.2.41, location estimate Manchester Session still active The sign-in succeeded, so this is a record of what happened rather than a warning that something was blocked. Your password has not been changed. If it was not you, select End all sessions and change your password. Both are on the Security page. Reference: SIGNIN-A41C
The location is labelled an estimate. A security message should not imply that an approximate signal is certain, and it should not hide the controls the reader needs. This is informational writing with a consequential conditional action attached, which puts it in the same ethical family as an error message, because the reader may act on it within seconds.
A search that returns nothing also reports information rather than a breakdown. The catalog distinguishes a completed search with zero matches from a failed search, and names the filters responsible for the narrow result. Without verified retrieval and a known index status, the same sentences would be an unsupported assurance.
Case 19. A successful search with no matching records
No matching records were found. The search itself completed successfully. Query "quarterly forecast" Scope All company documents Searched 2,406,118 documents Filters Owner: you, Modified: last 7 days Duration 0.42 s The index is current as of 15:40 BST, so no matching document exists within these filters. The search did not give up or time out. Please remove the "Modified: last 7 days" filter to inspect the 14 broader matches; removing both filters matches 212.
The empty result is supported by the search that ran and by the index snapshot available to it. It does not establish that no relevant record has been added since indexing, nor that some other filter would find nothing. A message should expose index freshness when that distinction bears on the reader's decision.
Every notice can be tested with one question: what will be different for this reader after reading it? Sometimes the answer is to save before Saturday. Sometimes it is to migrate by March, or to remove a filter, or to do nothing at all if the sign-in was theirs. A notice that cannot answer the question may be noise, however polite its salutation.
J00Confirmation describes the current decision
Confirmation is not a flourish added in front of an alarming button. It is a statement of the choice the application is about to carry out. The reader needs a faithful description of the affected objects, the environment, the consequence, and the available ways to inspect, decline, or correct the decision.
For consequential web submissions, W3C's error-prevention criterion describes safeguards such as reversibility, input checking with a chance to correct, or review and confirmation before finalizing. The criterion does not demand a solemn dialog for every save. It does make clear that a sentence alone is no safeguard if the interface never gives the reader a real chance to review or reverse a serious action.
The target in the next specimen is a production table that sits outside the stated snapshot. The message gives a count, a date range, a request identifier, the absence of recovery, and an exact confirmation phrase. It says that deletion has not happened, and asks the reader to review an export before making the final choice.
Case 20. An irreversible operation with a specific confirmation
May I impose upon your attention before this becomes a matter for apologies? The selected command will permanently delete 438 records from the production database. Please review the record list, then type delete 438 production records to confirm. Request DEL-20260927-438, initiated by m.hughes at 15:06 BST Table orders_archive Records 438, dated 1 January to 31 March 2019 Database production Recovery none; this table is outside the nightly snapshot Nothing has been deleted. Because no recovery is available, choose Export record list and review the full list before entering the confirmation phrase.
That phrase means something only if the software binds it to this verified record set and checks it again at execution. A decorative text box that accepts the words while deleting a newly expanded selection would misrepresent consent. The catalog includes a second, unusually revealing moment. After the reader reviewed 12 files, a nightly import added three more. The earlier preview no longer described the operation, so the confirmation has to be renewed.
Case 21. A confirmation invalidated by a changed selection
The preview has been overtaken by events.
You reviewed a deletion affecting 12 files. The folder now contains
15 matching files, so the previous confirmation no longer describes
the proposed operation.
Request DEL-2048
Folder /exports/month-end
Reviewed at 27 September 2026, 11:02 BST, 12 files, 840 MB
Now 15 files, 1.1 GB
Added since march-adjustments.csv, q3-accruals.csv and
supplier-credits.csv, by the nightly import at 11:14
Deletion has not started. Please review the updated file list and
confirm again. The three new files are marked in the list so that the
difference does not have to be found by eye.
This second message explains the difference instead of leaving the reader to find it. It also states that deletion has not started, a claim that needs proof from the operation's own state. It is not merely a nicer way of asking again. The proposed action changed, and authorization for the old action does not automatically cover the new one.
The same principle governs a choice among conflict policies, a permission grant, or a payment amount. Where a preview can go stale, the interface must compare it against the current state at the point of commitment. Wording can reveal the discrepancy. Only the product design can stop the old confirmation from going through in silence.
K00Someone else has edited the record
A document may be perfectly valid and still impossible to save as submitted. Another editor can change the server revision while the first person is working. A bare "conflict" label tells neither person whether their text has been lost, whether the newer work is safe, or how to reconcile the two.
The catalog's revision example identifies the base revision and the newer one, summarizes what each side changed, locates the overlapping paragraph, and keeps the first person's unsaved text in the editor. It offers a comparison and a merge instead of quietly choosing a winner.
Case 22. A revision conflict that keeps the local draft
Your changes deserve consideration alongside a more recent development. You began editing revision 18. The server now holds revision 21, saved by another editor. Your changes have not been applied to that newer revision. Record Employment Terms, DOC-1842 Detected 27 September 2026 at 14:31:18 BST Your edits 412 words added, 2 paragraphs removed, since 14:02 Their edits revisions 19, 20 and 21, by s.okonkwo, 14:08 to 14:31 Overlap one paragraph, "Termination and notice" Please compare the two versions, then merge your changes or reload the current record. Your unsaved text remains in this editor until you choose, and neither choice discards it without asking.
This message has two people in mind even though it addresses one. It protects the current editor from losing 412 words, and it protects the other editor's revision 21 from being overwritten without review. The promise that neither choice discards unsaved text has to be matched by the controls, by the draft's persistence, and by whatever the page does on reload. An application that cannot preserve the draft must not promise that it has.
Nothing here is an error. Two legitimate pieces of work have arrived at the same paragraph. Politeness in this case means making room for both facts and giving the two editors a way to resolve the overlap themselves.
L00The limits of stopping and undoing
Cancel and Undo sound complete. In a distributed system they usually name a boundary instead. Work still held inside this application may be stoppable. Work already accepted by a provider may be beyond recall. A previous document revision may be restorable while email notifications and downloaded copies stay exactly where they are.
Consider a batch of 120 messages. The provider has accepted 86, and 34 remain under the application's control. The cancellation message counts both groups and explains why sending a corrected batch to all 120 could produce duplicates.
Case 23. A cancellation that cannot recall accepted messages
I can stop the remaining work, but I cannot recall what has already departed. Of the 120 messages in this batch, the email provider has accepted 86 for delivery. The remaining 34 have been cancelled. Messages already accepted by the provider cannot be recalled through this service. Batch MSG-20260927-0901, "October statement ready" Started 27 September 2026 at 09:01 BST Accepted 86, between 09:01:04 and 09:02:18 BST Provider reference PVD-771842 Cancelled 34, none of which left this service Please review the delivery report under Activity > Delivery reports before starting a replacement batch. Sending the corrected version to all 120 could give up to 86 recipients two statements.
The undo in the next specimen has a similarly bounded reach. It restores the document text. It does not take back a collaborator's notification or erase a copy already downloaded. The message describes those external effects before asking the reader to choose.
Case 24. An undo that restores text but not outside copies
An undo is available, though its reach deserves to be stated
precisely.
Undo will restore the document's previous text. It will not withdraw
the email notification already sent to collaborators or erase copies
they may have downloaded.
Document Supplier Agreement, revision 15
Saved by e.rahman at 14:30:42 BST on 27 September 2026
Notified s.okonkwo, t.nakamura, a.whitfield and d.lindqvist, at
14:31 BST
Downloaded 2 completed downloads, by s.okonkwo and t.nakamura
Please choose Undo to restore revision 14, or keep revision 15.
Either way, both revisions remain in the document history and neither
is destroyed.
The distinction is practical rather than philosophical. "Your document has been restored" can be true at the same moment that "the incident has been undone" is false. Before publishing an undo message, inspect what the operation reverses, what it cannot reverse, and whether a time window applies. Where the interface offers only a brief recall period, its countdown and final state should be explicit. Where it offers durable version history, say which revisions remain.
This family of messages also shows when a short note is enough. A local, reversible formatting change needs little more than "Undo available" and a control. A sent notification or a deleted production record demands a fuller account, because the consequences have already left the application.
M00Responsibility is a verifiable statement
Sometimes a service ought to say that the difficulty is its own. That is not the same as accepting blame by reflex. A generic server error does not prove that the reader's parameters were valid, that no report was partially created, or that no quota was charged. The next example can say those things because it names the incident, the affected cluster, and the refusal of new work. Each assurance still rests on the system's own evidence.
Case 25. A product-side failure with a named incident
The request appears perfectly reasonable. The failure is on our side. Requested GET /v2/reports/monthly Returned 503 Service Unavailable Duration 45.0 s, timed out Incident REP-2026-0927-04, opened 08:40 BST Your parameters were valid and would have produced a report. The reporting cluster lost two of its three nodes at 08:40 BST and the remaining node is refusing new work rather than serving slowly. No report or partial report was created, and nothing has been charged against your API quota for these attempts. Status updates are posted at status.example.com. Once incident REP-2026-0927-04 is marked resolved, retry the same request without changing its parameters.
The specimen invites a retry once service recovers. That instruction is sound only if the report's status and the quota accounting both show that another attempt will neither duplicate work nor incur a second charge. If the first request might still be running, check its reference before offering Retry at all.
A candid message can also hand the work to a person. The escalation example gives the Payments team a case reference, the context already passed across, an expected response window, and an undertaking that no further refund will be submitted while the case is open. That undertaking belongs to the organization, not to the copywriter.
Case 26. A human handover with continuity
This has gone beyond what I can settle on my own. It has been passed to the Payments team, who have everything described here. Case CS-77410, opened 27 September 2026 at 15:02 BST Concerns refund pi_4471_rf1 against order SO-61250 Passed to Payments, at 15:04 BST Response within one working day; they will write to you They have the provider reference, the timings and the two attempts already made. Nothing needs repeating for them. No further refund has been submitted, and none will be while the case is open. Please quote CS-77410 in any reply.
The promise of no further refund needs an actual operational hold, or a workflow that prevents duplicate issuance. A support case label cannot guarantee it by itself.
The handover is valuable because the reader need not retell the provider reference or submit another refund just to make progress. It also settles where responsibility now sits. Where no team has yet received the case, the software must say that escalation has been requested or is still pending. "Passed to Payments" reports a completed event, not an intention.
References should connect what the reader sees to a record that support staff can actually retrieve. A reference no system recognizes is decoration. A response time no team has agreed to meet is an unearned assurance. Consideration for the reader includes the administrative work behind the words.
N00How much ceremony can a message bear?
The Courteous Machine is an exercise in a particular character. Its openings run from light through formal and ceremonial to theatrical. Those terms describe language rather than severity. A simple correction usually wants one specific fact and one direct action beside a form field. A consequential deletion wants a careful account of the affected set. A rare internal mishap, in a product that welcomes humor, can allow the machinery a little embarrassment, provided the facts stay in view.
The migration example is knowingly theatrical. The machine admits that it mistook progress for completion, then states immediately where the copy stopped, why the destination rejected four videos, which parts finished, and what the old and new sites are serving right now.
Case 27. Theatrical self-deprecation with a complete state account
I appear to have mistaken a promising beginning for an actual
accomplishment. The website migration stopped at "copy media library"
because the destination rejected files larger than 100 MB. Please
remove or split the four oversized videos, then resume the migration.
Migration MIG-2047, to sites-eu-03
Completed database, 2,104 pages, 18,402 small media files
Stopped 27 September 2026 at 04:12 BST
Remaining wedding-highlights-master.mov 1.2 GB
conference-keynote-raw.mov 1.1 GB
product-launch-uncut.mov 880 MB
staff-interviews-full.mov 620 MB
The old site is still serving and has not been touched. The new site
holds everything except those four files and can be previewed now.
The humor is aimed at the system's own pretensions. It does not imply that the reader was foolish, and it does not hide the four remaining files behind a joke. Even so, that opening would suit nobody reporting missing wages, a security incident, or an irreversible deletion. The catalog marks many elaborate entries as contextual for exactly this reason.
The voice also has to acknowledge a genuine tension with established practice. GOV.UK's validation guidance favors concise field messages and advises against "sorry" and "please" in that setting. Microsoft's error-message guidance likewise emphasizes clear, localizable wording and cautions against anthropomorphism. This project deliberately explores a more literary product voice. Use it where that voice serves the audience, and let it yield to direct, unambiguous instructions when the task requires them.
A good courtesy opening can be one short clause. Repeating it in front of every technical detail turns consideration into delay. Strip out every trace of voice, though, and the project loses its central experiment. The editorial question is whether the courtesy changes the reader's experience without making the message harder to understand on a first reading.
O00The sentence and the screen
A message may be perfectly written and still fail its reader by appearing in the wrong place, vanishing too quickly, or staying silent to assistive technology. A field correction belongs with its field, and should be reachable from the form's error summary. A background completion can appear as a status update with a route to its result. A consequential confirmation needs its reviewed object and its choice in the same interaction, not on an earlier screen the reader can no longer see.
W3C's status-message criterion covers updates that appear without moving focus. Success, progress, waiting states, and errors should all be programmatically available to assistive technology. The criterion governs how a status is presented, and the wording governs what it means. Both matter. A screen reader user should not have to infer a completed export from a silent change in button color, and a sighted reader should not have to decode a red banner that says only "something went wrong."
An essay can print the full version of a specimen for study. A product often needs two layers: a short primary statement in the moment, and particulars available to anyone who wants them without being shouted on every status change. Which details go where depends on the task. The refund's unknown outcome belongs in the primary message immediately. A stack trace belongs in a diagnostic channel, and a request reference may sit on a quieter details line. Put technical information where its intended reader can use it.
Dates need time zones when people in several regions may act on them. Locale-dependent numbers need a clear decimal convention when the value is money or a quantity. Control names should match what the interface displays. Long labels must wrap without losing the action. When a message is translated, an archaic metaphor may need a different expression to preserve the intended clarity, and a template destined for localization should not have English word order and punctuation built into it.
No phrase settles any of this on its own. A product should test its wording in the actual flow, with the data the application can observe, the controls it provides, and the audiences it serves. Politeness is one quality of that experience. It does not excuse the interface from accessibility or from honest state reporting.
P00How the collection was made
The Courteous Machine is a curated reference rather than an empirical study of which phrases make people happier. The project's visible source material yielded 572 distinct wordings. An editorial pass kept 110 of them for their distinct ideas, registers, or forms. Twelve new entries filled identified gaps, and 104 longer passages from a later submission were kept after four repetitive ones were set aside. The selected catalog therefore holds 226 entries across twenty-three categories, mixing short phrases, worked examples, patterns, complete passages, and a small set of counterexamples.
The provenance has a limit worth stating plainly. The supplied conversation began mid-example and indicated that earlier text was missing. The catalog and this essay account for the visible supplied material. Neither claims to recover an unseen beginning. The specimens here were chosen for the different decisions they expose rather than as a ranking of the most entertaining openings. Their catalog IDs will find the full entries and their editorial notes.
The catalog marks some entries ready to adapt and others dependent on context. Both kinds require the underlying facts to be true. A counterexample stays in the reference so that a writer can see why a tempting assertion or metaphor should be changed. It is not approved copy. Several entries were revised on technical grounds, because a refused connection did not prove which host declined it, a missing acknowledgement did not prove failure, or a retry instruction needed a status check first. Those repairs are part of the point of the collection. Polished manners never authorize an unsupported inference.
The offline reference around this essay lets a reader search by situation, form, and register, adapt a message in the constructor, and generate a function that composes the text in one of eighteen languages. That generated function cannot determine whether a request actually succeeded. That determination belongs to the calling application and the services it observes. The phrasebook is a starting point for writing and review rather than an oracle about runtime state.
Q00A test at the correspondence desk
Before releasing a message, read it as a person who has just seen it after doing something that mattered. Then work through the list:
- Can the reader identify the event and the object without opening a log?
- Is the described state supported by evidence available at this point in the workflow?
- Does the wording separate what is completed from what is pending or unknown?
- Are the consequence and the next action specific enough to follow?
- Does that action exist in the interface, and is it safe under the system's retry, undo, and permission rules?
- Would a person using assistive technology receive the same essential information?
Where any answer is no, revise the product behavior, the message, or both. Sometimes the best editorial change is to remove a claim. Sometimes it is to add a record count, a time zone, a reference, or the words "I cannot confirm." Sometimes it is to make a genuine handover to a person. The courteous style survives these revisions because its purpose is to treat the reader with consideration, and accurate information is a form of consideration.
The Bespoke compiler may insist on a graceful salutation. A person using software is owed something more durable: an intelligible account of what has happened, what has not happened, what remains uncertain, and what can be done next. If the machine can manage all that with a measure of good manners, so much the better.
R00Sources and reading notes
The creative point of departure is Bespoke: A Programming Language for People Who Say Please by Christian Hofstede-Kuhn. Its fictional programming language inspired the voice. The essay above concerns messages written for people using software.
The examples come from the project's content/catalog.json. Every specimen here reproduces the catalog wording and sample particulars exactly, and the identifier in its caption points to the corresponding record and editorial condition. The visible-source limitation and the selection counts are documented in the project README and editorial review.
For independently published guidance, see:
- The GOV.UK Design System on error messages
- W3C on error identification
- W3C on status messages
- W3C on safeguards for consequential submissions
- Microsoft's error-message guidelines
- Stripe's documented idempotency behavior
These sources inform the factual constraints discussed above. None of them endorses this project's period voice, and none of them suggests that the sample messages here were tested with users.