skim-001 should GuidesAPI docsMarketing Lead with the most important information; front-load key points so content is scannable.
Writing for skimming
Most readers of developer docs scan a page for the piece they need rather than reading top to bottom. This page covers how to order information so that scanning works. Related structural tools (headings, paragraphs, and lists) have their own pages.
Front-load key information
Section titled “Front-load key information”Examples
- ✓ Quotas limit how many requests each project can make. This page shows how to view and raise them.
- ✗ Before we discuss quotas, it helps to review some background on how the platform manages capacity.
Rationale
Readers scan, so front-loading the key point means they get it even if they do not read on.
Open with the subject, not the setting
Section titled “Open with the subject, not the setting”skim-002 should GuidesAPI docsMarketingBlog Make the subject clear in the first sentence or two: what the thing is, or the first thing the reader needs to do. Don’t open with a general observation about the industry, the importance of the topic, or its history. A phrase such as “This page describes” is acceptable, but it takes space that search results and summaries show; when brevity and clarity conflict, prioritize clarity.
Examples
- ✓ Webhooks notify your server when an event occurs in a project. This page covers how to register one and verify its signature.
- ✗ In today’s fast-paced digital landscape, real-time integration has become essential. Webhooks are a cornerstone of that shift.
Rationale
Readers scan for the answer, and a scene-setting opener is the part they skip. Starting with the subject puts the answer where they look first, and in the excerpt that search results show.
Don’t end with a recap
Section titled “Don’t end with a recap”skim-003 should GuidesAPI docsMarketing Don’t end a page with a conclusion or summary that restates what the page said. End with the last step, the last fact, or a “What’s next” section that points to the next task. A whitepaper or report that readers read start to finish can keep a conclusion.
Examples
- ✓ ## What’s next
- ✗ ## Conclusion
- ✓ After the migration finishes, the old table is read-only for 30 days.
- ✗ In summary, this guide walked through migrating a table, verifying the data, and cleaning up.
Rationale
A recap adds nothing a reader can act on, and readers who scan never reach it. Pointing to the next task gives the ending a job.