ABOUT · HOW THIS IS WRITTEN
How Software Made Clear is written
Software Made Clear explains technical ideas with public documentation, small reproducible examples, and diagrams that show one claim at a time. Articles name what was checked and when, so readers can verify important points themselves.
Think of a map with its source and scale printed beside it. It helps you find the route, and you can check how it was drawn. An article here should do the same: show the idea clearly and name the public material behind its claims.
Software Made Clear explains software concepts in a form someone without the writer’s context can follow. Articles use public documentation, specifications and small examples that readers can inspect. They do not draw on private employer or client systems, incidents or data.
The aim is to make a difficult idea both understandable and checkable. A short answer gives the result. The article then shows how it works, where the explanation stops applying, and what tends to go wrong.
The site does not ask you to take an unsupported claim on trust. Each article names the public documentation, specification or source code it was checked against, and the date — the note at the foot of the idempotency explanation shows the format. When a source contradicts a claim, the claim needs to change.
Content is English first. There are no German articles yet. When they come, they will be written by hand for articles that have proven themselves rather than translated — a German article is allowed different examples and a different structure.
How a diagram gets made
01 — One picture, one sentence. The sentence is written down before anything is drawn. If it takes two sentences, it is two diagrams.
02 — The picture belongs in the text. It sits beside the explanation, often wider than the text column. The site’s quiet paper canvas groups the figure without turning it into a widget — the traversal walk-through is one page built that way.
03 — Colour-coded nouns. A noun in the prose wears the colour of its object in the picture, so you build the legend while reading without noticing.
04 — Motion only as meaning. Animation shows change over time or it does not exist. Nothing starts on its own, and reduced motion gets the end state.
Contact
Corrections and questions are welcome, and the address is on the Imprint page. If a page here is wrong, that is the fastest way to get it changed.
Colophon. Astro with a small number of islands. Diagrams are hand-written SVG with no framework, coloured only through tokens. The Privacy page describes the current data collection and browser preferences.
Newsreader — display. IBM Plex Sans — text. IBM Plex Mono — code.
SELECTED WORK 03 EXAMPLES
See the ideas at work.
Three places to inspect the writing, interaction and interface design.