Chapter 2 · Practice 2 of 5
Structure posts so skimmers find the answer fast
Why it matters
Most readers skim first, then read the part they need. Help them:
- Start with the answer or result in the first paragraph. Put the background after.
- Use descriptive headings that say what each section does.
- Show prerequisites up front: versions, tools, assumed knowledge.
- Keep paragraphs short and use lists for steps.
- End with a summary and links to the official docs.
A reader who lands from a search should know within ten seconds whether the post solves their problem. If they have to scroll past your life story to find out, they leave.
Do
- Put the answer in the first paragraph
- List versions and prerequisites at the top
Avoid
- Long personal introductions before the useful part
Example
# Fix "too many connections" in PostgreSQL
Short answer: add a connection pool and cap it below max_connections.
## Prerequisites
PostgreSQL 16+, Node.js 22, the pg package.
## Why it happens
## Step 1: Check current connections
## Step 2: Add a pool
## Step 3: Set the pool size
## Summary and further reading