> ## 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.

# Describe branching procedures

> When a procedure splits by platform, role, or preference, how you handle the fork determines whether users find their path or get lost.

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>;
};

Many setup procedures branch. Install on macOS or Windows. Configure for the cloud or on-premise version. Authenticate with an API key or OAuth.

Throughout your documentation, you'll need to describe how to handle these branching procedures.

Help your users find the right information and avoid content that doesn't apply to them.

## Three approaches to branching procedures

### Tabs inside a step

When the differences are short—a few lines each or a single code block—and part of a procedure, put the options inside a tab within the step that diverges.

````mdx theme={null}
<Steps>
  <Step title="Install the package">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash
        brew install mintlify
        ```
      </Tab>
      <Tab title="Windows">
        ```bash
        winget install mintlify
        ```
      </Tab>
    </Tabs>
  </Step>
  <Step title="Verify the installation">
    Run `mintlify --version` to confirm the installation succeeded.
  </Step>
</Steps>
````

This keeps the procedure together and makes it clear the variation applies specifically to that one step. The steps before and after are the same for everyone.

Be aware that not every reader notices tabs. So be cautious about what information goes into tabs. If anything is applicable to both paths, make sure it is not hidden in only one tab.

Use tabs inside steps when:

* Only one or two steps in the procedure vary by platform.
* Each variation is short and fits within a single step, not an entirely separate procedure.
* The reader doesn't need to make a meaningful decision about which path to take or the selection criteria are obvious like picking their operating system.

### Separate how-to guides

When the differences between branching procedures are more in depth, or the choice affects more than just a few steps, write separate guides and link to them from a decision point.

```mdx theme={null}
Choose the authentication method that fits your setup:

<Columns>
  <Card title="API key authentication" href="/guides/auth-api-key" icon="key">
    Best for server-to-server requests and scripts. Simpler to set up.
  </Card>
  <Card title="OAuth 2.0" href="/guides/auth-oauth" icon="lock">
    Required for accessing user data. More setup, but more control.
  </Card>
</Columns>
```

This approach is easier to read and easier to maintain when the procedures diverge significantly. Readers self-select into their path and follow that guide from start to finish.

Make sure people are finding the right guide for their path. Review feedback and search results related to the guides to identify gaps and areas for improvement.

Use separate guides when:

* The differences between procedures involve more than 3-4 steps each.
* The procedures require different prerequisites.
* A user who takes one path will never need the other.

### A prerequisite step that routes the reader

For longer procedures where the initial steps are identical but the later steps diverge, make the branching point clear before the user begins the shared steps. This avoids frustration from having readers discover halfway through that they need to take a different path.

```mdx theme={null}
Before you begin, decide which path applies to you:

- **If you're deploying to the cloud**, follow steps 1-4 and then continue to the "Cloud deployment steps" section.
- **If you're self-hosting**, start at step 5 and then follow the rest of the steps.
```

This way, readers know up front how the procedure branches out, and can follow the correct path without having to backtrack.

This is a lightweight version of the separate-guides approach. It's appropriate when the branching is modest—one path has a few different steps but most of the procedure is the same—and you don't want to maintain two parallel guides.

## What to avoid

A common mistake is embedding a branch mid-procedure without clearly signaling it.

```mdx Example of an unclear branching point theme={null}
<Step title="Configure authentication">
  Add your key to the config file if you're using API key auth. For OAuth, you'll need to register a client application first.
```

This forces every reader to understand both paths to figure out which applies. Even users who know exactly which auth method they're using have to read carefully to make sure they're not missing something.

The fix is to make the decision explicit before the step begins, or use tabs so the paths are visually separated.

<Quiz
  question="A setup guide has 8 steps total. Steps 1 and 2 are identical for everyone. But the rest of the procedure varies completely by whether the user is on a free or paid plan. What's the best approach?"
  answers={[
{ text: "Tabs inside each step for users to select their plan.", correct: false },
{ text: "A single guide with a note explaining which steps to skip and which to complete based on a user's plan.", correct: false },
{ text: "Two separate guides, linked from a decision point.", correct: true },
{ text: "Two separate accordion sections for the free and paid paths.", correct: false },
]}
  correctFeedback="Right. When the majority of a procedure varies, separate guides are cleaner than embedding a branching point in the procedure. A decision point routes readers to the right guide without forcing them to read instructions that don't apply to them. And even if the first two steps are similar, the majority of the procedure is different enough to warrant separate guides."
  incorrectFeedback="When most of a procedure diverges, embedding the fork in the middle creates cognitive overhead. Readers have to continuously track which path they're on. Separate guides, linked from a decision point, let readers commit to their path and follow it straight through."
/>

<Check>
  Next up: [When a procedure outgrows a page](/courses/components/complex-procedures) — How to recognize when a procedure is too long for one page, and how to restructure it.
</Check>