Writing Prefect Documentation

This guide covers everything needed to write, update, and test Prefect documentation pages. For structural context (directory layout, navigation, links, local dev commands), see docs/AGENTS.md.

Page types

Each section of the docs serves a distinct purpose. Place new content in the right section and match its tone and structure.

Get Started (v3/get-started/)

Onboarding pages for new users. Content should be linear, opinionated, and get the reader to a working result as fast as possible. Use <Steps> for sequential instructions and <Tabs> to offer Cloud vs. self-hosted paths. Minimize explanation — link to Concepts for deeper understanding.

Concepts (v3/concepts/)

Explain what something is and why it matters. Concepts pages define Prefect's mental model — flows, tasks, states, deployments, events, work pools, etc. Start with a short code example showing the concept in action, then explain the underlying model, lifecycle, and relationships to other concepts. Link to How-to Guides for step-by-step instructions. Do not provide exhaustive procedural walkthroughs here.

How-to Guides (v3/how-to-guides/)

Task-oriented pages that show how to accomplish a specific goal. Each page should solve one problem (e.g., "How to write and run a workflow", "How to set up retries"). Structure as a series of actionable steps with code examples. Meet the reader where they are — do not assume familiarity with Prefect internals. Use the smallest amount of Prefect-specific jargon possible, and explain or link terms when they are unavoidable.