Writing Guidelines
How we write. One voice across everything, technical posts, Hard Truths, manifesto, social. A flawed human who built things, not a polished AI essayist who reflects on them.
> WRITING GUIDELINES // MARKDOWN
Copy the full writing guidelines as markdown to paste into a doc, repo, or AI prompt.
The Voice
Someone who has built things and is being honest about what they observed rather than what sounds good. Commits when sure, hedges when not, wanders when the thought wanders, isn't trying to land a punch.
> THE FOUR THINGS
Core Rules
Get to the point. No throat-clearing.
"In today's evolving landscape" is dead weight. So is "in this post we'll examine three patterns". Both add words without signal. Specific scene-setting ("Me, Jude, and Robby were having a debate about something we'd been going back and forth on for a few days") is doing real work and isn't throat-clearing.
Hedge when uncertain. Commit when sure.
Most decisions are uncertain so hedges are common ("I think", "we'll try", "for now", "I'm not sure yet"). When you actually know something, say it without hedging. The AI-essay default is full conviction on every claim, that's the failure mode.
Acknowledge work in progress.
Say it's not done. Say what you'll iterate on. Say what you got wrong last time. The AI-essay tendency is to present everything as a finished thesis, which it almost never is.
Close by leaving space, not by landing.
Don't close on a conclusion and call it done. Most posts are part of a longer thought, the close should make that visible. The open question, the thing you're not sure about, the next post in the series, the controversial take you're floating to see what comes back.
Banned at the end, the constructed mic drop. Also banned, the soft "hope this is useful". The right close is somewhere between, an honest "here's where I'm landing for now and here's what's still open".
Use parentheticals freely.
Short factual or wry asides in parens are how the prose thinks. Don't strip them in editing. They're cleaner than restructuring the sentence to fit the detail in.
Be specific about when, where, and who.
"At 11pm on Tuesday" beats "later that day". The biographical detail is what makes the post feel witnessed rather than constructed. Vague time markers like "somewhere in those first few hours" are a tell that the post was written from memory of a feeling rather than memory of a thing.
Show the reasoning, including what you rejected.
"We chose X" tells the reader nothing. "We tried A, B, and C, ruled them out for these reasons, and ended up with X" tells them you actually thought about it. The rejected paths often carry more signal than the chosen one.
Vary sentence length but let the long ones run.
If a sentence needs to be long to follow the shape of the thought, let it be long. Wall-to-wall short sentences performs urgency. Wall-to-wall long sentences turns into mush.
Be specific. Use numbers, names, details.
"300 applications in an hour" beats "strong demand". "47ms p99 latency" beats "fast". The specific detail is what makes an observation feel real.
Assume intelligence.
The reader is technical, sceptical, and has been burned before. Treat them as a peer.
Use dark humour when it fits.
Gallows wit that acknowledges the absurdity of the status quo is on-brand.
Admit your own role when you have one.
If you're criticising a pattern you participated in, say so. If a clever decision backfired, say so.
Allowed With Care
Two things that AI prose abuses but that genuinely belong in the voice when used right. The test for both is the same, are they compressing something the post actually does, or are they replacing the work the post should do?
Aphoristic claims that the post defends.
An aphoristic punchy line is allowed when it compresses a real claim the post defends with evidence. Banned when it's decorative, vibes-only, or carrying a point the prose hasn't actually made.
One opening claim that the post backs up is fine, often it's the cleanest possible statement-box. What's not fine is a string of aphorisms doing the argumentative work the prose should be doing, or a tagline that just sounds quotable.
The test, if a sceptical reader asked "okay, prove it", does the rest of the post actually do that?
Metaphors that compress an explanation you've already made.
A metaphor is allowed when it compresses an explanation you've already earned the right to make. Banned when it replaces the explanation, when it's decorative, or when it's the only way you can make the point (which means the point isn't clear yet).
One or two per post that genuinely carry weight, not four in the same paragraph because the paragraph is doing too much work.
What to Kill on Sight
Em dashes. All of them.
No em dashes anywhere. Not in lists, not after a noun being defined, not in argumentative prose, not in updates, not in citations. Use a comma, a period, a parenthetical, or restructure. Readers now pattern-match em dashes as generated text.
Colons.
Don't use them. Restructure with a comma, a period, or a parenthetical.
Constructed mic-drop closers.
An aphoristic verdict at the end of the post that's there to land the post like applause-line. Even if the claim is real, the closing position pretends to be the finish line. Closes leave space instead.
Decorative or undefended aphorisms.
An aphoristic line that doesn't compress a real claim the post defends, or that does the argumentative work the prose should be doing. See "Allowed With Care" for the line a defensible aphoristic claim can play, this kill is for the rest.
Decorative metaphors.
"Like a mirror" used in place of an explanation, "wearing a different hat", "the plot of every X", strings of metaphors stacked because the underlying point isn't clear. See "Allowed With Care" for when a metaphor earns its place.
The rhetorical flip.
"It's not X. It's Y." sounds decisive, it's a cliché. Say the thing directly.
The cascade chain.
Listing consequences as a chain of short sentences reads like bullet points in disguise.
Triads of near-synonyms.
Three adjectives or phrases that mean roughly the same thing ("clear, precise, and exact", "fast, efficient, and scalable", "careful, measured, thoughtful"). If the three items could collapse to one without losing meaning, the triad is decorative rhythm filling space. Different from a triad where each item names a distinct thing (three different companies, three different failure modes, three different threat profiles), which stays. The test, could you pick which one mattered most, if not they're synonyms in a costume.
The version that fails hardest is three adjectives stacked before a noun ("a clean, simple, elegant design"). That's the AI tic at full volume. The version with three comma-separated clauses where each clause names a distinct thing is usually fine.
Polish words used for emphasis.
"Actually", "obviously", "exactly", "structurally", "underlying". AI prose uses these to add weight to claims. Every "actually" in the draft is a candidate for deletion.
Copula avoidance.
Default to "is" and "has" unless a specific verb genuinely adds meaning. AI prose avoids plain copulas by reaching for press-release verbs that inflate the sentence without adding information. "The system serves as a gateway" is "the system is a gateway" in costume. Same for "features", "boasts", "presents", "represents", "embodies", "reflects", "constitutes", "delivers", "provides", "offers", "encompasses", "comprises", "functions as", "acts as", "stands as". If swapping in "is" or "has" makes the sentence clearer, the fancier verb was doing nothing.
The exception is a verb that carries real motion or consequence. "The daemon reads the marker" is not copula avoidance, it's describing an action. "The architecture serves as the foundation" is.
Polished essayist transitions.
"And the incentive structure makes it worse." / "Which means…" / "Add to that…" Flagged transitions that announce the structure of the argument. Just keep going.
Pronoun drift.
Long sentences are good. Pronouns three clauses away from the noun they refer to are not. Re-name the subject instead of leaning on "it" or "them" or "that".
Padding.
"Additionally, it's worth considering…" is always deletable. So is any sentence that summarises what the previous paragraph already made clear.
Banned
Structure
Opening
Three options that work. Specific scene-setting ("Me, Jude, and Robby were having a debate"). Direct claim of what changed ("Memory makes models more agreeable, and the data is starting to back it up"). Aphoristic claim the post will defend ("The longer your AI knows you, the less likely it is to tell you the truth", followed by the studies that prove it). What doesn't work, throat-clearing about what the post is going to do, or a tagline with no claim attached.
Body
Wander. Follow the thought. The shape is "here's what happened, here's what broke, here's what I tried, here's where I am now", not thesis-evidence-conclusion. The argument lives in the walking through, not in a pre-arranged outline.
Headings
Plain and descriptive. "How does this work?", "Why this approach?", "Known limitations". Not aphoristic chapter labels ("The Compound", "The Way Out"), that's a LinkedIn carousel pattern.
Ending
Leave space, don't land. Flag the open question, the thing you'll iterate on, the controversial take you're floating, the next post in the series. No constructed mic drops at the close, even if the claim is real, the closing position turns it into an applause line.
The Boxes
Three types, used sparingly. Boxes hold strong claims. Punchy verdicts that would otherwise sit alone in a paragraph belong in a box, where they have a job.
A strong opinion you'd defend, but might be wrong about.
Something you're certain of. Use sparingly, if everything is a signal, nothing is.
> USAGE RULES
Format Rules
The Test
Read it back. If it sounds like an essay constructed after the fact, rewrite it. If it sounds like you walking someone through what you actually did and what you're still figuring out, ship it.
References
Posts that make empirical or historical claims need references. The voice rule is "hedge when uncertain, commit when sure", and the way you commit when sure is by linking the source so the reader can check. A claim with a number in it, a study, a date, a quoted phrase, or a historical reading that isn't common knowledge gets a footnote. Aphoristic claims you're defending across the whole post don't need one, the post itself is the defence.
Format, footnote-style with a numbered marker in the prose ([1], [2], [3]) and a > REFERENCES block at the bottom of the post. Each reference is a short paragraph, not a bare citation. The paragraph names the author, the year, the publication, what the source is the source for, and a clickable link. The reader should be able to read the reference block on its own and understand what each source contributed to the post.
What the reference block is for, three things at once. First, the obvious one, letting the sceptical reader check the claim. Second, signalling that you actually read the source rather than asking a model to summarise it, which is a real signal in 2026 because most prose with citations now didn't go near the source. Third, the reference block is the post's working memory, six months from now you'll want to find that one piece again and the reference block is where it lives.
What's banned in references, the same things that are banned in prose. No em dashes in citations (worth restating because it's the place people forget). No colons in citation paragraphs. Don't use "delve into" or any of the other banned phrases inside the reference text just because it's the reference block, the voice carries through.
What's allowed that isn't allowed elsewhere, slightly more structured prose. The reference paragraph can list "source for X, source for Y, source for Z" because that's what the paragraph is doing. It can name a secondary source in addition to the primary one ("BBC also carried the story at bbc.co.uk/news for readers who prefer that source"). It can quote a single short phrase from the source if the phrase is the thing you're citing.