A FIELD GUIDE TO CIVILISED SOFTWARE
B00 / WORDS FOR THE OCCASION
Find the right words for the moment. Borrow a phrase, explore a pattern, or compose a complete message.
Try a broader search or clear the filters.
C00 / THE COMPOSING ROOM
Choose a situation or bring a phrase from the reference. Supply the facts, then adjust the ceremony.
D00 / THE WRITING DESK
Let the courtesy carry the voice. Let the facts carry the message.
E00 / ENTER GRACIOUSLY
Apology, interruption, regret and confession are different entrances. Choose the one that fits. Stacking them delays the useful information.
I beg your pardon, but the requested file could not be opened.
F00 / NAME THE OBSTACLE
The records office may be closed to visitors, but the reader still needs the host, port and observed error. A connection refusal alone does not establish which machine or policy rejected it.
The connection to <host>:<port> was refused. Please verify the service and network configuration.
G00 / ACCOUNT FOR THE STATE
Say what completed, what did not, and what remains unknown. "Nothing has been changed" and "rolled back" require evidence. A missing success record is not proof of failure.
The request may have completed before communication was lost. Please check its status before repeating it.
H00 / OFFER THE NEXT MOVE
Use a direct verb, a specific object and a realistic next step. Do not promise recovery, monitoring or notification unless the software provides it.
Please close the workbook and try the export once more.
I00 / THE MESSAGE GRAMMAR
These are optional parts, not seven compulsory paragraphs. A small validation issue may need one sentence. A partial deployment needs an explicit account of completed, failed and uncertain work.
J00 / FOUR REGISTERS
| Register | Voice | Use it for |
|---|---|---|
| Light | Pardon me, but... | Frequent validation and routine guidance. |
| Formal | I beg your pardon, but... | Ordinary failures and permission boundaries. |
| Ceremonial | Pardon the interruption. | Deliberate attention and consequential decisions. |
| Theatrical | With considerable embarrassment, I must admit... | Rare internal defects in products that welcome comedy. |
Severity does not automatically call for comedy. Never trivialise loss, security incidents or financial uncertainty with "one small matter".
L00 / WITH THANKS
This reference owes its premise to Bespoke: A Programming Language for People Who Say Please on the Larvitz Blog, which imagined a language that will not compile without courtesy. The joke there is the argument here: politeness costs a program almost nothing, and the reader is owed both the manners and the facts.
The tool mark on each entry opens a code generator, so a chosen phrase can leave this page as a small function in eighteen languages. Syntax highlighting uses a modified copy of microlight by asvd, used under the MIT licence.
This collection began as every distinct wording in the visible supplied conversation, some 572 entries. That proved more than anyone could read. Each entry was then judged against every other for what it alone contributed, and the phrasebook was reduced to the 110 that earned their place: the clearest statement of each idea, in each register that idea uses, across all twenty-three categories and every form the collection uses.
What was removed was repetition rather than substance. Twenty ways of saying “nothing has been changed” became four. Ten interruption openers became two. Bare vocabulary fragments, which were words rather than messages, went entirely. Where two entries said the same thing, the richer one stayed.
Reading the survivors as a set showed what the source conversation had never discussed, so twelve entries were written to close those gaps: work still in progress, a deprecation notice, payment details about to expire, a retention deletion announced in advance, an unrecognised sign-in, an available update, an undo window, a finished background job, escalation to a person, an inactivity sign-out, a temporary lock, and a request the service cannot perform. That gives the 122 published here.
A later submission offered 108 further messages, each a complete passage of three or four paragraphs rather than a sentence: an opening in the right register, the particulars, a limit stated plainly, and a closing instruction naming the controls by name. These were reviewed for uniqueness against each other and against everything already published, and four were set aside because another entry already taught the same lesson: a replacement service carrying traffic, which repeats a verified deployment; the use of a compressed image, which repeats an image optimisation; the acceptance of machine-suggested edits, which repeats a machine-drafted revision; and a format retirement, which repeats the deprecation notice written earlier. The surviving 104 are published word for word, with their paragraph breaks, their control labels and their blanks exactly as received. That gives the 226 published here.
Every entry carries a hand-written worked example: the same wording as it would appear in real software, with concrete particulars. A passage needs no separate example, being already a complete message; where one contains blanks, it can be read with sample values instead. Discouraged wording is retained as a counterexample, hidden from the default view, and its example shows the courteous form instead. Contextual phrases carry usage notes. Necessary technical revisions show both edited and original wording.
Raw supplied text / Follow-up chat examples / Supplied passages / Structured catalog / Editorial review / README