Writing
How the words on the site are set. These are the conventions the writing already follows, read back from the site itself: the public output standard, not the process behind it.
Sentences
The default sentence puts its subject first, then the verb, then the object, and stops. Most sentences on the site are built that way on purpose: the writing serves four languages, and many readers take it in a language that is not their first. A plain sentence asks nothing extra of them; the clever construction is saved for the one moment in a section where the argument peaks.
- Inverted openings. A sentence that withholds its subject makes the reader wait for it. “The third arrangement grows into a maintenance bill” beats “what quietly turns into a maintenance bill is the third arrangement”.
- Animated abstractions. A reason does not pay off and a release does not step aside. Lifeless things are described, not handed verbs that belong to people: “you end up building by hand what a library would give you for free”.
- Decorative tails. Once the point has landed, an ornamental clause hung on the end carries rhythm but no information, and draws attention to the writing. It gets cut.
- The paragraph that keeps proving itself. Point, evidence, move on. A paragraph that restates its point in new words reads as distrust of the reader. Cover its last sentence: if the paragraph still lands, that sentence goes.
The test is to read the paragraph aloud. Any sentence that makes you double back to find its subject gets flattened, and one inversion per section, placed where it earns its keep, is the ceiling.
Do
Don’t
Plain words
Short, common words beat inflated ones. Marketing vocabulary (robust, seamless, cutting-edge, battle-tested) claims quality instead of showing it, so a concrete fact takes its place. Filler transitions (moreover, furthermore, additionally) and Latinate padding go the same way: use over utilise and leverage, then over subsequently, so over therefore.
| Avoided | Used instead |
|---|---|
| robust, seamless, battle-tested | the measurement, or the fact |
| moreover, furthermore, additionally | and, also |
| therefore, thus, consequently | so |
| leverage, utilise | use |
| delve into, dive into | look at |
| ultimately | in the end |
A word earns its place back when it is the literal technical term: a software framework is a framework, dynamic dispatch is dynamic. The marketing sense of the same word never qualifies.
Three smaller rules travel with this one. Idioms are replaced with their literal meaning (differs rather than parts company), so a reader in a second language never has to unpack a folded phrase. Acronyms and tool names are spelled out on first use: “SWC (the Speedy Web Compiler)”. And the seesaw construction, “it is not X, it is Y”, is restated as the positive claim, the half that carries the information.
Do
Don’t
Spelling
Prose is British English: behaviour, colour, organise, licence. The two exceptions are deliberate and both live in code, not prose. A code identifier keeps whatever spelling its API uses, so a color property stays color. And across the Module Federation writing, artifact is a term of art (a published, versioned module), so it keeps that spelling while ordinary prose still writes artefact.
Do
Don’t
Case
Sentence case is the house style: page titles, section headings, article headings, buttons and labels capitalise the first word and any proper nouns, and nothing else. The top navigation is the one standing exception, kept in title case.
Do
Don’t
Dates
Dates are British. An article date spells the month in full: 29 March 2026. A role range abbreviates the month and keeps the year (Mar 2016 to the present), and an open range closes with the word Present, never a trailing dash.
Do
Don’t
Punctuation
The serial comma is the default: labels, hints, and states. Exclamation marks stay out of prose. Truncation and loading states use the single ellipsis character, an aside sits in commas or parentheses, and a metadata row separates its parts with a middot. Three full stops in a row belong to code, not sentences. The em-dash is the scarcest mark on the site: commas, colons, parentheses and full stops do the everyday work, and a dash used everywhere loses its force. Two places remain for it: a label set against its gloss, as in reference rows, and the rare aside no quieter mark can hold. It never splices two independent sentences together; that joint takes a full stop or a colon.
Do
Don’t
Links
Link text describes where it goes. The site never links the words click here or read more, or a bare here or this; a link reads as the thing it points at.
Do
Don’t
Brand and product names
Product names keep their official spelling and casing. React Native and Module Federation are two title-case words each; Pokémon and Pokédex always carry the accent; App Store is two words. Where a name has an exact form, match it rather than tidy it.
Do
Don’t
Cross-linking
Posts point at each other freely: a sentence that mentions the token-refresh post links to it, with the link text naming the destination as above. Links may even point at posts that have not shipped yet: the words render as plain text, so nothing ever 404s, and they become a link on their own when the target publishes. Forward references are written once and resolve themselves.
Each post can hand-pick up to three related posts; posts without picks fall back to shared tags. A further-reading shelf tops that up with quieter posts the reader has probably not met, capped at nine in total, so it stays a recommendation rather than an archive.
Inside a series, previous and next stay inside the series: part five points at parts four and six, never at an unrelated post that happened to publish next to it. Only at the ends of a series do the arrows fall back to the neighbouring post by date.
Disagreeing in print
Technical writing here disagrees a lot: with defaults, with popular libraries, with received wisdom. The rule is to steelman first. State the opposing view in its strongest form, credit what it gets right, then show where it stops working for the case at hand. The disagreement lands as an observation about fit, not a condemnation.
Do
Don’t
Two habits support it. Claims that are not absolute are not written as absolutes: “X never works” becomes “X was not designed for Y”. And there are no defensive openers: sentences do not start with “To be clear” or “Just to clarify”.
Three more habits keep arguments honest. A design choice is named as a choice, never dressed as a law of nature: “the host owns navigation” is a decision this build makes, and saying so invites the reader to follow the reasoning instead of hunting for counter-examples. Because is reserved for causality the text has shown; where a claim rests on inference or convention, the writing says “which suggests” or “the usual reason is”. And headings describe fit rather than failure: “Where X has limits” over “Why X fails”.
Social teasers
When a post is shared on LinkedIn, the share is a teaser, not a summary. Its one job is to open a curiosity gap the article closes: state a tension, name a specific detail without explaining it, and point forward. If the reader feels satisfied without clicking, the teaser failed.