Writing Guidelines

Docs succeed because of hundreds of small decisions. This is a living, non-exhaustive list of those decisions, drawn from the Vercel docs handbook and the patterns that hold up across hundreds of pages. Most guidelines are framework-agnostic, with a few Vercel-specific conventions called out at the end.

Outcome Contract

• Outcome: A technical doc draft or revision that complies with the rules below.
• Done when: Content type declared; banned words eliminated; every code block has a language tag; headings are sentence case.
• Evidence: Section-by-section self-check against this file; no rule skipped silently.
• Output: The revised doc, plus a short list of rules consciously not applied and why.
• Authorization: Edit documentation only — do not touch code, config, or product copy outside the doc surface.

How to Apply

1. Pick the content type first (Tutorial, How-to, Reference, Conceptual, Troubleshooting, Landing) — it drives the shape.
2. Draft the five-section plan (overview, goal, audiences, documentation plan, open questions) before writing prose.
3. Write applying Voice & tone and Structure rules as you go.
4. Finish with a typography and source-formatting pass (quotes, ellipsis, units, wrapping).
5. If an LLM drafted any part, follow the AI workflow section: disclose, and do a final human review.