Prerequisites
A prerequisites section lists what a reader must have or do before they start the procedure. It lets a reader confirm they are ready — and, if they are not, stop before hitting a wall midway through the steps.
When to use
Use a prerequisites section on any page with a procedure that depends on prior setup: accounts, permissions, compute, enabled features, or installed tools. Tutorials and how-to pages almost always have one; a pure concept page does not.
Composed of
- Headings — an H2 titled Prerequisites or Requirements.
- Lists and links — one item per prerequisite, linking setup docs.
- Admonitions — call out a non-obvious permission or a version floor.
Technical details
- Choose the heading by what the section contains:
- Prerequisites: preparation the reader must complete before the rest of the page, such as installing a tool, creating a resource, or finishing another tutorial.
- Requirements: conditions that must be true for the rest of the page to work, such as versions, permissions, enabled features or previews, or pricing plans (see Requirements).
- Don't use Before you begin as the heading.
- Write each prerequisite as a bullet, and link to the doc that explains how to satisfy it.
- Order from most fundamental (an account) to most specific (a particular setting).
Rules
- List only what the page's procedure actually needs. Do not pad with unrelated setup.
- Every prerequisite that has its own setup doc must link to it.
- State version floors and required permissions explicitly.
Style
- Phrase items as things the reader has or has done: "The Databricks CLI, installed and configured"
for prerequisites, "The
CREATE TABLEprivilege on the schema" for requirements. - Keep each item to one line where possible.
Template
Markdown
## Prerequisites
Before you start, you need:
- <Prerequisite, linked to its setup doc.>
- <Prerequisite.>
Examples
Prerequisites
Before you start, you need:
- The Databricks CLI, installed and configured.
- A catalog and schema to hold the tutorial tables.