Distribution craft

Distribution Craft

The article doesn't end at the last paragraph. A piece that took 20 hours to research and write often gets 2 minutes of distribution attention — and then dies in a noisy feed because the title was generic. Distribution craft is the practice of giving the article a fair chance.

This skill covers the layer between the article and its readers: title, dek, meta description, social pull-quotes, channel framing. None of this is the substance of the article — but all of it determines whether the substance ever gets read.

Core principle

Titles do most of the work; treat them as a discipline. A great article with a weak title reaches a tenth of the readers a great article with a strong title would. The asymmetry is enormous; treat title craft as seriously as paragraph craft.

Secondary principle: the same article reads differently to different audiences. A piece that converts on Hacker News may bounce on LinkedIn (and vice versa). Channel framing isn't dishonest — it's the same substance, packaged for the venue the reader is in.

Title craft

The single highest-leverage 8-12 words you'll write.

Three things a title must do

1. Promise something specific the reader values.
2. Differentiate from the noise around it.
3. Honor the article — not over-promise, not under-promise.

A title that does all three is rare. Most titles do one (specific) at best.

Title formulas that work

The classic patterns from a century of headline writing — adapted for technical content.

"How we [did specific thing] [with surprising detail]"

"How we cut Postgres latency 80% by removing one index"
"How we migrated 100k tests in 11 weeks (without breaking production)"
"How we deleted 47 microservices in one quarter"

The "how we" frame promises a story; the specific detail (80%, 11 weeks, 47) earns the click. Works for case studies.

"Why [conventional view] is wrong (and what to do instead)"

"Why TDD doesn't work for the median team (and what does)"
"Why microservices were a mistake for most teams"
"Why your CI is slow and how to fix it"

The contrarian frame promises differentiation; the parenthetical "and what to do" promises constructiveness. Works for opinion.

"The [specific kind of bug/problem/pattern] that [cost/changed/revealed something]"

"The Postgres setting that's costing you 30% of your disk"
"The deploy bug that took down our pipeline for three days"
"The TypeScript pattern that made our codebase 2x faster to type-check"

The frame teases a specific revelation. Works for narratives and deep-dives.

"[Specific number] things I learned from [specific experience]"

"5 things I learned from a 6-month Rust migration"
"3 lessons from running 100k experiments at GitLab"
"What 11 weeks of test migration taught us about test architecture"

Listicle-shaped but anchored in specific experience. Works when the experience is unique.

"[Tool/technique] for [specific use case]"

"PostgreSQL row-level security for multi-tenant apps"
"Ruby's pattern matching for parsing tree-sitter output"
"Bun's test runner for incremental migration from Jest"

Direct, searchable, low-curiosity. Works for tutorials and how-to guides where the audience is already searching.

"[Number]-minute [topic]: [specific value]"

"The 5-minute Postgres health check"
"A 2-hour deploy pipeline rewrite (and what we learned)"

Frames the time investment; promises proportional value.

"What [respected source/event] taught us about [topic]"

"What the Slack outage taught us about distributed-system blast radius"
"What 6 months of OpenAI's status page taught us about uptime claims"

Borrowed authority; specific event lends credibility.

Anti-formulas (don't)

Pattern	Why it's bad
"The Ultimate Guide to X"	Promise inflation; reader doesn't believe it
"Everything You Need to Know About X"	Same
"X: A Complete Tutorial"	Marketing-coded
"Mastering X in [N] Days"	Self-help-coded
"The Future of X"	Generic; predicts nothing specific
"X is Dead"	Cliché; rarely true
"Why X Will Change Everything"	Hyperbole tells the reader to discount
"X 101"	Tells novices "this is for you" but loses everyone else
"Beyond X: Y"	Pretentious; the reader cares about X or Y, not the journey
Single-word titles ("Resilience.")	Vague; competes with nothing

The 8-12 word rule

Most strong titles land between 8-12 words. Shorter often vague; longer often loses energy.

✗ Too short (5 words):   "Postgres performance lessons learned"
✓ Right length (10):     "The Postgres setting that's eating 30% of your disk"
✗ Too long (16):         "Lessons learned from a comprehensive Postgres performance investigation in our production environment"

Exceptions exist (some tight 5-word titles work), but 8-12 is the safe band.

Title testing

If you're not sure between candidates, test:

1. Read each aloud. The one that reads cleanest usually wins.
2. Show three friends. Which would they click? Which is clearest?
3. Search for it. If your candidate title shows existing articles with very similar titles, you're competing in noise — differentiate.
4. Strip the curiosity test. Does the title still tell the reader what they get even with all curiosity-bait removed? If not, you're relying on bait.

The honest-title constraint

A title's job is to describe accurately what the reader will get. Curiosity is fair; misleading is not.

Honest curiosity	Dishonest bait
"The Postgres setting that's eating 30% of your disk" (article delivers the setting and the calc)	"The shocking truth about Postgres" (article doesn't deliver shock)
"How we cut latency 80% by removing one index" (we did)	"The one weird trick to cut latency 80%" (no trick; cheap framing)
"What 6 months of OpenAI status pages taught us" (we read 6 months of pages)	"The dark secret OpenAI doesn't want you to know" (no secret)

The asymmetry is brutal: dishonest titles get a one-time click and zero return readers. Honest specific titles compound trust.

See references/title-craft.md for the full title formula library and worked transformations.

Dek craft

The dek (subtitle, standfirst, deck) is the second sentence the reader reads. Its job: confirm the title's promise and earn the read.

Dek formulas

Pattern	Example
Restate + specify	Title: "Why TDD doesn't work for the median team." Dek: "TDD is a discipline that pays off at scale; for teams of 5-15 it usually adds cost without proportional benefit. A look at why, and what works instead."
Promise + scope	Title: "The Postgres setting that's eating 30% of your disk." Dek: "How dead tuples accumulate, why VACUUM can't always clean them up, and the alert that catches the problem before you run out of space."
Story setup	Title: "How we deleted 47 microservices in one quarter." Dek: "We had a distributed monolith pretending to be microservices. Here's how we noticed, what we cut, and what we kept."
Expectation set	Title: "The 5-minute Postgres health check." Dek: "A six-query script you can run on any database to find the most common operational problems. Designed for teams without a dedicated DBA."

Dek length

Usually 25-50 words. Shorter risks losing the second hook; longer competes with the article body for attention.

Dek anti-patterns

• Repeating the title. "Why TDD doesn't work for the median team." Dek: "TDD doesn't work for the median team because…" Wastes the dek.
• Hyping the dek. "An incredible deep dive into the world of…" — adjective inflation tells the reader to discount.
• Promising more than the article. Dek over-promise is the same trust failure as title over-promise.

See references/dek-and-meta.md for the full dek and meta-description craft.

Meta description (and open-graph)

The meta description appears in search results and social previews. Often 150-160 characters.

Meta description formula

[Article promise in one sentence], [specific differentiator or detail].

"How dead tuples accumulate in Postgres, why VACUUM can't always clean them up, and the
 6-line alert that catches the problem before you run out of disk."

158 characters. Carries the promise and a specific detail.

Open-graph image

The image shown in social previews. Two patterns:

1. The article's title rendered well. Clean typography, brand-consistent. Works when title carries the substance.
2. A graphic / chart from the article. Works when the article has a memorable visual.

Avoid stock photos. They tell the reader the content is generic before they read.

Social pull-quotes

Per channel, the article needs different framing.

X / Twitter

The tweet announcing the article should:

• Lead with a specific value-claim (not the title).
• Include the link.
• Optionally end with a hook for engagement.

✗ "New post: 'The Postgres setting that's eating 30% of your disk' [link]"
✓ "Most Postgres databases I've audited have 18% dead tuples. Here's how that happens, why
   VACUUM can't always fix it, and the 6-line alert that catches it before you run out of
   disk: [link]"

The second version sells the article in 280 characters; the first only labels it.

Tweet thread version

For high-stakes articles, a thread can preview the substance:

1/ Most Postgres databases I've audited have 18% dead tuples. Not 2%, not 5% — eighteen
   percent. Here's how that happens.

2/ MVCC keeps both versions of an updated row. Concurrent readers see consistent snapshots.
   The cost: dead tuples.

3/ VACUUM cleans them up. But VACUUM can't run while a transaction older than the dead
   tuples is still open.

4/ So one engineer's lunch-time psql session, left open for an hour, can prevent VACUUM from
   running on your entire database.

5/ Here's the alert that catches it: [link]

Threads earn engagement (each tweet a chance to retweet) but cost more time. Use selectively.

LinkedIn

LinkedIn rewards different framing:

• Open with a personal angle ("I spent 6 months researching this").
• Include a takeaway readers can use.
• Avoid Twitter-shorthand vocabulary.
• Length: 100-300 words; LinkedIn favors longer posts than Twitter.

"I spent the last quarter auditing Postgres databases for clients. The most common
 operational issue wasn't what I expected.

 It wasn't slow queries. It wasn't bad indexes. It was dead tuples — the byproduct of
 Postgres's MVCC system that accumulate when VACUUM can't run.

 In the worst case I saw, 84% of the database was dead tuples. The team was paying for
 storage they couldn't actually read.

 The cause was almost always the same: a long-running transaction blocking VACUUM, often
 from an unrelated batch job or a forgotten psql session.

 I wrote up the mechanism, the audit query, and the alert that catches it: [link]"

Hacker News

HN rewards:

• A title that signals depth (not "10 tips" but "How X works").
• An honest, specific submission title.
• A first comment from the author with context (not promotion).
• A topic that intersects with HN interests (developer tools, infrastructure, security, performance).

HN doesn't reward:

• Marketing language.
• Listicles.
• Anything that reads as content marketing.

The submission title can be the article title (preferred) or a more direct version:

Article title: "The Postgres setting that's eating 30% of your disk"
HN title:      "Diagnosing Postgres dead tuples accumulation"

The HN version trades curiosity for clarity — HN readers prefer the second.

Reddit

Per subreddit; varies wildly. /r/programming favors HN-style titles. /r/devops favors operational specifics. /r/PostgreSQL favors technical depth.

Reddit titles must comply with subreddit rules and avoid feeling promotional. Submit infrequently; engage in comments substantively.

Newsletter

If sending to a newsletter:

• Subject line is the highest-leverage element.
• Often the same as the article title, occasionally adapted.
• Preview text (the second line shown in inboxes) acts like the dek.

Subject: How dead tuples accumulate in Postgres
Preview: Why VACUUM doesn't always run, and the 6-line alert that catches it

See references/social-pull-quotes.md for per-channel patterns and worked examples.

Channel framing

Same article, different framing per channel. Not different articles — different windows into the same article.

What changes per channel

Element	X	LinkedIn	HN	Reddit	Newsletter
Title	Curiosity-led	Personal-led	Specific / accurate	Subreddit-appropriate	Like article
Length	280 chars (or thread)	100-300 words	Title only	Title + auto-text	Subject + preview
Tone	Conversational	Professional	Direct	Per subreddit	Per newsletter voice
Hook	First 100 chars	First sentence	The title itself	The title itself	Subject line
Link	Always	Always	Always	Always	Always

What doesn't change

Element	Across channels
The article's substance	Same
The honesty of the framing	Same
The voice	Same in spirit; adjusted to register
The promise to the reader	Same

Channel framing is re-presenting the same article, not pretending it's a different article.

See references/channel-framing.md for per-channel deep-dives and worked transformations.

✅ Use for

• Writing a title for a finished article
• Suggesting 5-10 title candidates and picking the best
• Writing a dek / subtitle / standfirst
• Writing a meta description for SEO
• Pulling 3-5 social quotes for X / LinkedIn from the article
• Reframing the same article for HN, LinkedIn, X, Reddit
• Writing a tweet thread that previews the article
• Writing a newsletter subject line + preview text
• Auditing existing distribution copy

❌ NOT for

• The article body itself — use long-form-structure / engaging-craft / long-form-polish
• General SEO (keyword research, on-page optimization beyond titles and meta) — out of scope
• Content marketing strategy — out of scope
• Short-form business writing (email subject lines for work, RFC titles) — use communication/structured-writing
• UI text or button labels — use ux-writing
• Paid promotion / ads copy — different discipline; out of scope

Anti-patterns

The afterthought title

What it looks like: Article gets 30 hours of work; title gets 30 seconds. Default to the working title.

Why it's wrong: Title is the single highest-leverage 8-12 words. The reach asymmetry is enormous.

What to do instead: Generate 10 title candidates. Read each aloud. Pick the strongest; sit on it for a day; reconsider. The 30 minutes earns more readers than another 5 hours of polish.

Clickbait

What it looks like: Titles that over-promise to earn the click. "The shocking truth…" "You won't believe…" "This one weird trick…"

Why it's wrong: The asymmetry is brutal. One bait-click, never returning. Trust burned.

What to do instead: Curiosity is fine; misleading is not. Make the title specific and accurate. Curiosity that pays off compounds; curiosity that doesn't burns.

The dek that repeats the title

Title: "Why TDD doesn't work for the median team"
Dek:   "TDD doesn't work for the median team because…"

Wastes the dek. The reader who clicked the title is now reading the same content again.

Fix: the dek confirms the title's promise and adds something — scope, specificity, hook.

Channel-blind cross-posting

The same exact post copied to X, LinkedIn, HN, Reddit. Each platform has different conventions; ignoring them costs reach on each.

Fix: invest 5-10 minutes per channel to reframe. The total time is small; the reach difference is large.

Promotional first comment on HN

The author posts a first comment that reads like marketing. HN downvotes; the article never gets traction.

Fix: if you post a first comment, make it substantive — context the article doesn't include, or an invitation to disagree on a specific point.

LinkedIn-as-Twitter

A 280-character LinkedIn post with a link. LinkedIn's algorithm favors longer-form; short posts get little reach.

Fix: write 100-300 words. Lead with personal angle. Save curiosity-style posts for X.

Social pull-quotes that don't appear in the article

Pulling a quote that's striking but isn't actually in the article. Reader clicks expecting that line; doesn't find it; bounces.

Fix: pull quotes only from the actual article. If the article doesn't have a striking quote-able line, write one and add it to the article.

Title rewriting after publication

Publishing with title A, then changing to title B based on initial signal. Fragments the article's identity (URLs already shared, screenshots floating around with title A).

Fix: spend the title-craft time before publishing. Once published, title is mostly fixed.

Workflow

1. Confirm the article is polished. Don't title until the body is done — the title may need to change based on what the article actually became.
2. List the article's promise in one sentence. The title is a compression of this.
3. Generate 10 title candidates. Use the formula library.
4. Read each aloud; eliminate weak ones.
5. Test the top 3. Read to a friend; search for similar titles; verify each is accurate.
6. Pick the winner.
7. Write the dek — confirm and extend the title.
8. Write the meta description — 150-160 characters; promise + detail.
9. Pull 2-4 social quotes from the article for re-use.
10. Reframe per channel — X version, LinkedIn version, HN version, newsletter version.
11. Open-graph image — clean typography or a chart from the article.
12. Sit on it — review the package the next morning before publishing.

References

File	Contents
references/title-craft.md	Title formulas, anti-patterns, the 8-12 word rule, testing protocol, worked transformations
references/dek-and-meta.md	Dek formulas, meta descriptions, OG metadata, open-graph images
references/social-pull-quotes.md	Per-channel patterns for X / LinkedIn / Hacker News / Reddit / newsletter; tweet threads; first-comment strategy
references/channel-framing.md	What changes vs what doesn't per channel; worked transformations of one article across X / LinkedIn / HN / newsletter

Related skills

• long-form-structure — the article's promise (set in structure) is what the title compresses.
• engaging-craft — title and dek inherit voice from the body.
• long-form-polish — distribution comes after the body is polished.
• technical-research — specific numbers from research feed specific titles.
• storytelling (skillstack) — narrative framing for non-technical pieces.
• communication/structured-writing (skillstack) — work-writing structure (BLUF, Pyramid) for memos and emails.