Technical content structure

Technical content structure

Getting a hurried developer to reach the last paragraph. Your reader is technical and short on time: they want the takeaway quickly, a thing that actually runs, and a reason to believe you. This covers readability; getting found is [[blog-seo-standards]]'s job.

Center the reader

• Frame every section around what the reader gets, not what you shipped. Open on the task they can now finish, the annoyance that disappears, the minutes they save. Recast "our team built X" as "here's how X gets Y done for you." A paragraph drowning in "we" is one to redo in the second person.
• Talk peer-to-peer, the way one engineer explains something to another — not a sales pitch. Plain and unfussy, a touch friendly, contractions welcome. Drop the hype words ("revolutionary," "seamless," "game-changing") and just demonstrate it.
• Keep the prose around a middle-school reading level — closer to a paperback than a spec sheet. Trim long words and sentences; a tricky idea lands better in simple language, so let the concept carry the difficulty, not the sentence. Spell out what isn't obvious, skip what is, and link out for background rather than rebuilding it inline.

Keep it skimmable

Solid blocks of text get abandoned — face a dozen dense paragraphs and a reader samples a couple then bails. Break the page up with structure and whitespace.

• Paragraphs: three or four sentences at most, one idea apiece. Past roughly six screen-lines, split.
• Something visual should interrupt the prose every few hundred words — a subheading, list, table, or image — giving the reader a fresh landmark to aim for. Include two or more genuine visuals (a screenshot, diagram, code sample, or video) so the page never reads as one long wall.
• Reach for a list only when the shape fits. Three-plus parallel items or ordered steps belong in one; a short or subtle set flows better as a sentence. Nonstop bullets tire a reader like nonstop prose.
• Put code in fenced blocks, not inline: any command past a few words, any JSON/YAML/config snippet, and any back-and-forth example — all fenced, with a language tag for highlighting.
• Links go inline behind a meaningful label, never a naked URL ("the setup guide", not the raw address). The lone exception is a line the reader will literally copy — a command or a value in a code block — where the URL itself is what they need.
• Go light on bold. Emphasize a word or two — a term, a UI label, a sharp contrast — never a full sentence (bolding everything emphasizes nothing) or the same word on repeat. Rule of thumb: past ~5% of a paragraph bold, or a bold run over ~4 words, thin it out.

Put the payoff first (the inverted pyramid)

People read the web the way they scan a newspaper: give them the outcome up front, then supporting detail in order of decreasing importance, so a reader who bails after the opening still walks away with what matters. Load the front of everything — a heading that says something, a topic-carrying first sentence per paragraph, the meaty words before the filler. Nielsen Norman Group's inverted-pyramid piece covers the why.

Show one clean route

Take the reader down a single path, not through every possibility as you go. With several choices (regions, OSes, auth flavors), build the main flow around the common one and hand the rest to the canonical doc ("Running a different X? Substitute your Y — full list here"); a table nobody needs is clutter, not care. And never leave a half-described escape hatch — "if X breaks, fall back to Y" with no steps is filler; write the steps or drop the line. Whatever you defer, make sure the doc covers it.

Headlines that pull their weight

Specific, outcome-first, keyword up front (length limits live in [[blog-seo-standards]]). Patterns that work: problem-to-solution ("From Three Dashboards to Three Questions"), a time hook ("41 APIs in 90 Seconds"), a before-and-after ("Governance: From Aspiration to Enforcement"). Steer clear of vague feature roundups ("What You Can Do with X"), the worn-out "7 Ways to…", and questions you never answer.

Open by covering the five W's

The first few lines should establish who it serves, what it's about, when it's relevant (a launch, a newly shipped feature), where the material comes from (link the docs behind it), and why it pays off — then finish with a quick roadmap: "we'll walk through X, Y, and Z." Slip in two things that quote well: a clean definition of any named concept ("X is a Y that does Z" — the line a snippet or AI overview lifts) and, when the work is yours, one first-person sentence of authority (E-E-A-T); the third person throws away a signal AI leans on.

Body — pain first, then the fix

Run each section as the problem (a sentence or two of concrete friction) → the change (the fix, with an example) → the proof (a before/after table or image) → the payoff (a one-line takeaway). Open on why anyone should care before the mechanics, and quantify the win ("8 min → 90 sec") instead of claiming it "makes things easier." Describing a chat-style interface? Write it as a real exchange (You: / Assistant: turns in a fenced block), not narration of what a reader might type — an actual transcript feels concrete.

Match the depth to who's reading: developers vs. architects

A technical piece earns its reader's time differently depending on who they are, and the two audiences judge it on opposite things. Decide up front whether you're writing for the person who will build the thing or the person who decides whether it should be built, then pressure-test the draft against that reader's bar.

For developers, abstract prose is dead weight — they came for something they can run.

• A section that stays conceptual with no code, API call, or command is one they scroll straight past. Ground each one in a snippet that actually executes.
• "Check the docs" is a dead end unless you name the exact page, class, or method — point at the precise thing, not the manual.
• When the topic touches data operations, cover the platform's limits, batch/bulk handling, and the error paths; leaving those out reads as inexperience and costs you trust.
• Don't sketch a pattern only in the abstract — show the real implementation (the class, the component, the endpoint) underneath it.
• Cut vague instructions like "call the appropriate method" or "handle errors as needed"; name the method and the specific error type instead.

For architects, the why carries as much weight as the what — they're weighing a decision, not copying steps.

• A flat recommendation with no trade-offs is half an answer. Say when the alternative is the better call, too.
• Give the reasoning behind a design, not just the build order — the rationale is the part they read for.
• For any integration or system-design pattern, address data volume, the sync-versus-async choice, and what happens when it fails; skip those three and the piece feels shallow.
• "This scales well" is an empty claim without a number or a named breaking point behind it.
• Recommending one option means comparing it to the realistic alternatives — name the competitors and why you passed on them. A recommendation with no rivals on the page is an assertion, not a decision.

Keep your labels consistent

Once a post falls into a repeating pattern, word that element identically every time — the before/after pair, the takeaway line, the table's column headers. Labels that wander turn tidy structure into noise. Settle the template before section one; on a revision pass, hunt down every stray variant and align them at once.

Close on the value, then send them onward

Finish with a genuine Conclusion on why the post was worth their time — the payoff — not a bulleted recap of everything above. Where it fits, add where to bring questions (a community, a Q&A site, social) and any fair call to action (a sign-up, a follow, a related product). End on two or three concrete next-step links, never a limp "Learn more."

When to set these aside

The rules chase skimmability and conversion. Set them aside for work needing academic rigor (papers, deep specifications) or narrative long-form where the telling is the point. Default everything else to skimmable.

How to revise

Change only what the request calls for; leave surrounding prose be; don't quietly reshape a voice or structure nobody asked you to touch. Ripple check: whenever you alter a claim, example, or framing, hunt for everything downstream that still assumes the old version (headings, captions, table rows, intro/outro summaries, an "as noted above"). A heading has to match whatever sits under it.

Pre-publish checklist

• Reader-centered framing ("you," not "we"); roughly a middle-school reading level
• No paragraph over four sentences; something visual every few hundred words; two-plus real visuals
• Opening covers the five W's and ends with a quick roadmap
• Every section leads with its point (inverted pyramid), pain before fix
• Depth matches the reader — runnable code + specifics for developers, trade-offs + rationale for architects
• Links inline behind real labels; lists used only where they fit
• Conclusion lands on the value and points to a next step (not a recap)
• SEO handled separately → [[blog-seo-standards]]