Documentation

Read the public project summaries

Written while the work happened: why each project exists, the decisions behind it, and how it developed.

Public summaries, private systems

The pages below are summaries, reviewed before publication. The systems behind them, including the source code, admin tools, operating instructions, and release records, are private. We do not publish access details, sign-in details, customer information, or other private operational material.

Reviewed public summarySouthpawStringsWhy the guitar site exists, why its tools open side by side, and how it was built.Reviewed public summaryDesk EngineWhy the window system became its own library, what it does, and how it protects saved layouts.Reviewed public summaryAI OrchestratorWhy AI-assisted coding needs a proper record, and why the rules are kept apart from the AI models.

How we write

How the documentation is written

Every project’s technical documentation follows one house standard, called STE-lite. It adapts ASD-STE100 Simplified Technical English, the aerospace standard for aircraft maintenance documentation, and pairs it with George Orwell’s six rules for plain English. Aviation writes for a reader under pressure who must not misread a step. An operator restoring a database at three in the morning is that reader too.

SentencesShort, single, activeInstructions stay under 20 words, descriptions under 25. Each sentence gives one instruction, starts with the action word, and says who does what. Paragraphs stop at six sentences.
WordsOne word for one thingA house term list fixes the vocabulary. It is always “deploy”, never “ship” or “roll out”, and always “verify”, never “check” or “confirm”. Words that mean different things, like secret, token and key, are kept apart on purpose.
StructureWarnings before the stepProcedures are numbered. Descriptions are not. A warning sits before the step it applies to, because one placed after has already failed. Conditions come first: “If the dump is empty, the script stops.”
OrwellClarity outranks the rulesShort words, fewer words, no worn-out metaphors or needless jargon. When the rules pull against each other, any step that could destroy data or take a live system down follows the strict rules. Everywhere else, the clearer sentence wins.
Reading orderIntroductions firstEach project opens with an introduction: the problem, the reasons for the design and how it was built, before any setup commands. The list of changes in each version lives in the changelog, not ahead of the explanation.
The recordHistory is never rewrittenChange logs, records of past decisions, and dated reviews stay as they were written. Rewriting them would falsify the record. A fact that changes often, like which version is live, is stated in exactly one place.

A worked example

One safety-critical sentence, before and after

Before · 50 words“Note: the migrate script now runs a mandatory, fail-closed pre-migration pg_dump preflight — it aborts the migration if the dump fails or is empty, so the tooling enforces this for you; this manual step is a belt-and-braces on top.”
After · four sentences“The migrate script makes a pg_dump backup before it migrates. If the dump fails, or the dump is empty, the script stops. It does not migrate. The manual step below is an additional precaution.”

The pile-up of nouns is gone, the condition comes first, and the worn-out figure of speech is cut. The longest sentence is now 12 words. (pg_dump is a standard database backup tool.)

How it is checked, and its limits

In the SouthpawStrings code, the build fails if a banned phrase appears in the covered documents. A separate score, for guidance only, counts long sentences, passive voice, and filler per hundred words. A check may fail a build only if it never flags a correct sentence. This is not certified ASD-STE100. It does not use the licensed dictionary of approved words, and a tool can measure the shape of a sentence, never whether it is true. Pages written for people, like this one, keep a human voice.