Overview
Articles on this site (and in pieces written from it) follow a stable skeleton: a lede that earns the next paragraph, sections that open with rules, and an ending that stops on its last real point. This page is the skeleton spec. For sentence-level rules, see voice and anti-slop.
Default skeleton
Use this skeleton unless the piece has a reason not to.
- Lede (one to three sentences). State the claim or the question. No throat-clearing.
- Stakes (one short paragraph). Why the reader should keep reading.
- Body (two to six H2 sections). Each H2 opens with a rule statement.
- Examples or case (one section). Concrete; show the code or the artifact.
- Caveats (optional). Name the cases where the rule does not apply.
- Hand-off (one paragraph or none). What to read next.
Skip sections, never fake them. A piece without real caveats does not get a caveats section.
Ledes
The lede states the claim, the question, or the artifact. Three patterns that work:
- Claim: “Postgres beats MySQL for application data.”
- Question: “When is SQLite the right database?”
- Artifact: “Below is the migration that finally made the table fast.”
Avoid throat-clearing openers. “In this article,” “Today we’ll look at,” and "Let's dive into" all delete cleanly.
Sectioning
One rule per H2. The H2 is the rule; the body is the rationale and examples.
- H2 reads as a rule, not a topic. “Lead with the rule,” not “Leads.”
- H3 only when an H2 splits cleanly into named sub-cases. Avoid H4.
- Two H2s minimum. Five to seven is a healthy upper bound. More than ten is two articles.
If two H2s repeat the same point, merge them. If one H2 carries half the article, split it.
Paragraphs
Three to seven sentences. Each paragraph carries one idea.
- Open with the idea. Develop it. Stop.
- No takeaway sentences. The reader knows what the paragraph just said.
- No paragraph-end transitions (“With that in mind,” “Building on this point”). Start the next paragraph with its own idea.
Lists
Use a list when the items are parallel and order-or-count matters. Use prose when the items want connective tissue.
- Three short items want a list.
- Three items where each needs a sentence of context probably want prose.
- Nested lists past one level are a smell; split into sub-sections.
Endings
End on the last real point. A summary paragraph that restates the lede is a slop tell, see anti-slop.
If a hand-off is useful, make it one sentence and link out. “For the deployment story, see github-pages.”
Length
Aim for the length the argument needs and stop.
- Reference pages on this site: 400 to 700 words.
- Long-form articles: 800 to 1500 words is the comfortable range; over 2000 should split into linked pieces.
- If a section exceeds the page budget, promote it to its own page and wikilink.
Revision pass
Two passes after the draft is done.
- Lede pass. Cut the first paragraph if the second works as the lede. Repeat until the opening earns its place.
- End pass. Cut the closer if the prior paragraph ends the piece cleanly.
Then read it aloud once. If a sentence trips, cut or rewrite.