> ## Documentation Index
> Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# When a procedure outgrows a page

> Long procedures are harder to follow than short ones, even when they're well-written. Here's how to recognize when to split a complex procedure into multiple pages.

export const Quiz = ({question, answers, correctFeedback, incorrectFeedback}) => {
  const [selected, setSelected] = React.useState(null);
  const [checked, setChecked] = React.useState(false);
  const quizId = React.useId();
  const isCorrect = checked && answers[selected]?.correct;
  const reset = () => {
    setSelected(null);
    setChecked(false);
  };
  return <div className={"quiz-container" + (checked ? " quiz-checked" : "")}>
      <Badge color="green">Quiz</Badge>
      <p className="quiz-question" id={quizId + "-question"}>{question}</p>
      <div className="quiz-options" role="radiogroup" aria-labelledby={quizId + "-question"} aria-disabled={checked}>
        {answers.map((answer, i) => <label key={i} className={["quiz-option", !checked && selected === i ? "quiz-option-selected" : "", checked && answer.correct ? "quiz-option-correct" : "", checked && selected === i && !answer.correct ? "quiz-option-incorrect" : ""].filter(Boolean).join(" ")}>
            <input type="radio" name={"quiz-" + quizId} checked={selected === i} onChange={() => !checked && setSelected(i)} disabled={checked} />
            <span className="quiz-radio" />
            <span className="quiz-option-label">{answer.text}</span>
          </label>)}
      </div>
      {checked && <div className={"quiz-feedback " + (isCorrect ? "quiz-feedback-correct" : "quiz-feedback-incorrect")} role="status" aria-live="polite" aria-atomic="true">
          <span className="quiz-feedback-icon">{isCorrect ? "✓" : "✗"}</span>
          {isCorrect ? correctFeedback : incorrectFeedback}
        </div>}
      <div className="quiz-actions">
        {!checked ? <button className="quiz-btn quiz-btn-check" type="button" onClick={() => selected !== null && setChecked(true)} disabled={selected === null}>
            Check answer
          </button> : <button className="quiz-btn quiz-btn-reset" type="button" onClick={reset}>
            Try again
          </button>}
      </div>
    </div>;
};

A procedure with fifteen steps is harder to follow than one with five because users lose their place. They have to remember how far through they are or how much is left, which becomes challenging if they're moving between your product in another tab or window and your documentation.

If they have to stop and come back, finding their position might require rereading content or starting over.

Some procedures are too long for a single page.

## Signs a procedure has outgrown its page

**The scroll is significant.** If users need to scroll multiple screens to see all the steps, the procedure is likely too long for a single page.

**Steps depend on decisions made far earlier.** If step 12 says "based on the option you chose in step 3," you're probably combining too many procedures into one.

**Some users don't need all the steps.** If steps 8-12 only apply to users with enterprise plans, those users have to read through steps 1-7 before finding out which path they're on.

**The page generates support tickets at a specific step.** If you can see from your analytics or support queue that users consistently get stuck at step 9 of 14, that step is probably the right place to make a page break.

## How to structure multi-page procedures

Two approaches work for most documentation.

* Short, complete pages that link from one to another.
* Tutorials that describe each step of a complex procedure, but link to specific how-to guides for more information on each step.

Each page should:

* Have a single, clear goal like "Connect your GitHub repository" or "Set up your deployment settings" (not "Setup, part 2").
* Be completable in one sitting.
* End with a clear indication of what comes next or success criteria to know that the procedure is complete.

Guide users forward at the end of each page.

```mdx Example of a card component used for a next step link theme={null}
You've connected your repository. Next, configure your deployment settings.

<Card title="Configure deployments" href="/guides/configure-deployments" icon="settings">
  Set your build command, output directory, and environment variables.
</Card>
```

Next steps can be simple. Just let people know what to do next and what they should expect if they follow a link.

```mdx Example of a prose next step link theme={null}
Next: [Configure your deployment settings](/guides/configure-deployments) — Set your build command, output directory, and environment variables.
```

Users who complete a page shouldn't have to navigate back to an index to find out what comes next.

## Update the navigation

When a procedure spans multiple pages, make sure the navigation reflects the sequence. In `docs.json`, list the pages in order within a group:

```json Example group theme={null}
{
  "group": "Set up your account",
  "pages": [
    "guides/create-account",
    "guides/connect-repository",
    "guides/configure-deployments",
    "guides/publish"
  ]
}
```

The sidebar order communicates the sequence. A user who gets lost can look at the sidebar and see where they are in the overall flow.

<Quiz
  question="A 14-step setup guide has steps 1-6 for all users and steps 7-14 for users connecting a GitHub repository. What's the best structure?"
  answers={[
{ text: "Keep it as one page because splitting creates more navigation overhead.", correct: false },
{ text: "Two pages. One for the procedure for all users (steps 1-6) and one for the procedure for GitHub users (steps 7-14).", correct: true },
{ text: "Tabs on a single page with 'All users' and 'GitHub users' as the two tabs.", correct: false },
{ text: "An accordion section for the procedure for GitHub users (steps 7-14) so GitHub users can expand it.", correct: false },
]}
  correctFeedback="Right. The natural split is at the point where paths diverge. Non-GitHub users finish on the first page. Only GitHub users must continue to the second page. Each page has a clear, complete goal. Tabs and accordions would bury steps 7-14 and risk GitHub users missing steps they need."
  incorrectFeedback="When the second half of a procedure only applies to some users, the split should happen at the branching point. Non-GitHub users get a complete, shorter page. Only GitHub users continue to the second page. Tabs and accordions are for content you want to show on demand, not for steps users must complete."
/>

<Check>
  Next up: [Code block essentials](/courses/components/code-blocks) — Write code blocks that help users follow along.
</Check>