Paragraphs

Readers of developer docs scan more than they read, and the paragraph is the unit they skip or commit to. These rules keep paragraphs short and focused with the key point first. Page-level scanning patterns are covered on the writing-for-skimming page.

One idea, key point first

para-001 should GuidesAPI docs

Keep paragraphs short and focused on a single idea; place the most important information first.

Examples

• ✓ You must enable billing before you can create an instance. To enable it, open the Billing page.
• ✗ There are a few things to consider when creating instances, and configurations vary by project, but note that billing must be enabled first.

Rationale

A short, single-idea paragraph with the key point first is easy to scan and skip.

Split long paragraphs

para-002 should GuidesAPI docs

Flag paragraphs exceeding five to six sentences as candidates for splitting.

Rationale

A paragraph past five or six sentences usually holds more than one idea and is worth splitting.