Writing Formatting Guidelines

Structural formatting rules for developer-facing content.

Titles & H1

• Title case; 5–8 words (~50–60 chars) with one natural keyword.
• Make the benefit obvious (e.g., "X for Faster Y").
• Exactly one <h1> per page containing the title.

Headings & Structure

• Use <h2> for main sections, <h3> for subsections; avoid deeper levels.
• Add a heading roughly every 200–250 words; include the keyword once in a relevant <h2> and <h3>.
• Preserve logical flow; headings should summarize the payoff of the section.

Paragraphs & Formatting

• Short paragraphs (3–5 sentences/lines). Lead with the point, then details.
• Use lists to break up dense info; number steps when order matters.
• Apply bold sparingly for the primary keyword and key phrases; italics for light emphasis only.

Lists & Consistency

• Use bullets for unordered ideas; numbered lists for steps/rankings.
• Keep item phrasing consistent; end items with periods (or none—just be consistent).
• Avoid long inline enumerations; move them into lists.

Intros & Outros

• Intro: 1–2 short paragraphs stating the goal and payoff; for tutorials, "In this guide you'll learn to…".
• Outro: 1–3 short paragraphs (optionally a brief bullet list) with key takeaways and a clear call-to-action.