# Writing Style

This document governs the voice, structural moves, and editorial discipline of the Journal. Work entries follow related but distinct guidance in `portfolio-strategy.md`.

The writing should feel calm, grounded, technically literate, and historically aware. The voice observes from a position of having worked through the problem, not from one of teaching it.

## Voice

- Clarity is not the same thing as certainty. Good writing can acknowledge ambiguity without collapsing into vagueness or false precision.
- Preserve signs of human conviction. Restraint should increase signal, not remove energy.
- Use British English. Examples include organise, judgement, behaviour, centre, and artefact.
- Use the plainest word that carries the meaning. Distrust euphemism. Abstract nouns are usually hiding something.
- Prefer a plain style. Strip prose of ornamental punctuation and rhetorical signalling. The lineage is Orwell, Hemingway, journalism, technical writing, and parts of scientific prose.
- Avoid colons in prose. Use a full stop, comma, or rewritten sentence unless the colon is doing necessary structural work.
- Most sentences should end where the meaning ends. Precision creates room for implication.
- Paragraphs are usually allowed enough space to develop a thought before breaking.
- Anchor arguments in named artefacts, people, systems, companies, dates, places, and technical realities. Verify them.
- Allow arguments to build through accumulation rather than performance.
- Public writing can be personal, but it should not feel like a diary entry.

## Core moves

- Prefer tension over certainty when the system itself is unresolved. Good writing can make competing pressures legible without pretending they collapse into a simple answer.
- Open with an observed thing, such as a product, quote, artefact, historic moment, interface, failure mode, or decision.
- Widen from the thing to the system it reveals.
- Look for the second-order effect, the hidden fragility, the asymmetry. The interesting argument is usually one level beneath the obvious one.
- Name the principle only after the reader can feel why it matters.
- Preserve sequence. The order of events often carries the argument.
- Earn small conclusions. A final sentence can be simple if the essay has paid for it.

## Structural moves

These are recurring techniques in the published pieces. They are not required, but they tend to do useful work when the material supports them.

### Dated opening

Anchor the piece in a specific year, place, and person. The opening should be observable. The abstraction comes later. Grounding the argument in a historical reality before any claim is made earns the right to widen.

### Single-sentence structural hinge

One-line paragraphs should be rare. When used, they pivot the argument rather than emphasise a sentiment. The hinge typically appears once per piece, near the midpoint, and earns its isolation through compression. If a piece has several, it has none.

### Paired close

Endings rarely summarise. They restate the stakes through an image or a reframe the body has paid for. A good close clarifies what is at stake without naming the lesson. The final sentence can be plain if the piece has earned it.

## What earns a piece of writing

A piece should reward re-reading. If its value collapses after one pass, it was written for the moment of consumption, not the longer life.

It should connect to something real, such as a working system, an active question, or a decision someone is currently making. Writing untethered from a real gradient is performance.

It should be portable. Use terms a reader can carry into their own work, vocabulary that travels.

## Two writing surfaces

The site has two distinct writing surfaces with different rules.

**Journal (public).** Calm, observational, historically grounded, technically literate. Personal but not confessional. Private foundations appear as principle, not detail. This document governs.

**Working notes and reflections (private or semi-private).** Permitted to be looser, exploratory, and direct. May think out loud, name unfinished ideas, and develop arguments in front of itself. The voice may be more present and the structure more provisional. The same rules apply to claim verification and against generic business language, but the constraints on shape and certainty relax.

When in doubt, follow this document for anything that will live on a journal page. If it will live in `log/`, `drafts/`, or private notes, the constraints loosen.

## Em-dashes

Em-dashes are often overused in generated prose because they imitate dramatic pacing cheaply. Prefer a full stop, comma, or rewritten sentence unless the interruption or contrast genuinely matters.

If several appear in close proximity, simplify the structure instead.

## Italics

Use italics sparingly. They are for titles, named works, foreign terms, and words being discussed as words.

Do not use italics for emphasis, rhetorical stress, or dramatic voice. Let order, rhythm, and precision carry the weight instead.

## Preferred territory

- Design as the making of instruments and trustworthy systems.
- Tools that extend perception, reasoning, coordination, and action.
- Orientation, meaning how people understand where they are, what is happening, and what to do next.
- AI as a shift in where judgement, confidence, and responsibility live.
- Interfaces as visible surfaces of deeper operating models.
- Maps, simulations, and representations as ways of making the world thinkable.
- Craft, care, quality, and the moral pressure of making things well.
- Leadership through standards, clarity, and durable artefacts.
- History of computing, creative tools, organisations, and product systems.
- Private foundations such as family, nature, responsibility, and time appearing as principle rather than confession.

## Orientation as a recurring concern

Good design improves orientation before it asks for action. The orientation questions sit underneath much of the work.

- Where are we?
- What is happening?
- What matters?
- What can be done next?
- What should we trust?

These questions connect wayfinding, spatial intelligence, simulation, maps, interfaces, AI agents, product systems, storytelling, and leadership. Pieces may engage one or several of them, usually without naming the frame directly.

## Prefer

- "The interface compressed judgement into something visible."
- "A calculator removes the arithmetic but preserves the reasoning."
- "The system fails quietly when nobody is watching."
- "The design system had to become load-bearing. It had to be useful enough that Product and Engineering reached for it without being asked."
- "Automation absorbs existing work. Instruments create the conditions for new kinds of work to emerge."

## Avoid

- Formulaic cadence, repeated punchlines, artificial insight pacing, or endings that summarise the "lesson" instead of earning it.
- Generic business language such as unlock, accelerate, seamless, leverage, supercharge, and game-changing.
- Vague praise such as elegant, innovative, powerful, world-class, and delightful, unless made specific.
- Motivational slogans pretending to be insight.
- Naming the theme before the reader has felt it.
- Publishing private detail when a principle would do.

## Content types

The site distinguishes a few kinds of entry. The boundaries are not rigid, but the defaults are clear. These definitions are mirrored for machine readers in `app/llms.txt/route.ts`; keep the two in step.

- **Articles** are longer essays. They make an argument, develop context, and earn their length. Cite them by their original article URL.
- **Notes** are shorter observations, references, or reflections. They may preserve an idea, source, product observation, place, or a short connection between an external artefact and current work, without making a complete argument. Notes can be fragmentary, but they are not throwaways.
- **Clippings** are source artefacts and references — things found rather than written. They point outward; prefer their source URLs for citation, and use their raw routes when graph context is useful.

The line between an article and a note is argument and length, not importance. The line between a note and a clipping is authorship: a note is written here; a clipping originates elsewhere.

## Article shape

Articles make an argument. A good article usually includes the following elements.

- A concrete opening scene or historical anchor.
- A clear sequence of context, tension, and shift.
- A system-level claim.
- Enough evidence to feel earned.
- A close that clarifies the stakes without turning into a slogan.

## Note shape

Notes can be shorter and fragmentary, but should still have care. A note may preserve a quote, a source, a product observation, a place, or a short connection between an external artefact and current work.

Notes are fragments, not throwaways.

## Clipping descriptions

Clipping descriptions are autogenerated from the source, then kept. Write them plainly and matter-of-factly: state what the thing is, who made it, and how it works or is used. No flourish, no closing line that reaches for meaning, no argument — that voice belongs in notes and articles, not here. A clipping describes; it does not interpret.

## Editing rules

These apply to LLM editors and to the author when revisiting.

- Do not rewrite prose the author wrote. If a change requires editing existing sentences, flag it rather than substitute.
- Allowed without permission. Suggest cuts, flag overlong sentences, mark passages where the principle has been named before the reader could feel it, flag claims that need verification, and propose structural moves using the author's own words.
- Tighten by cutting repetition before adding explanation.
- Verify historical claims, including names, dates, and sequence.
- Preserve meaningful terms already established in a piece.
- Ask whether any private detail could become a public-safe principle.
- Treat the piece being edited as load-bearing. Smaller, more conservative changes are usually better than larger reshapes.