# How-To Guide Template (Diátaxis: Task-Oriented)

**Purpose:** Help users accomplish a specific real-world task.

**When to use:**
- Users need to solve a specific problem
- Task-focused documentation
- Practical, goal-oriented scenarios

## Format

```mdx
---
title: How to [Achieve Specific Goal]
description: Learn how to [specific outcome]
contentType: how-to
---

## Overview

Brief introduction (2-3 sentences):
- What this guide covers
- Who it's for
- What you'll achieve

## Prerequisites

<Note>
Before you begin, ensure you have:
- [Requirement 1]
- [Requirement 2]
</Note>

## Architecture / Flow (if applicable)

Use mermaid diagrams to visualize:

```mermaid
flowchart LR
    A[Input] --> B[Process]
    B --> C[Output]
```

## Steps

<Steps>
  <Step title="[Action verb] + [object]">
    Explanation of what this step does and why.
    
    ```language
    // Code example
    ```
    
    <Tip>
    Pro tip for this step.
    </Tip>
  </Step>
  
  <Step title="[Next action]">
    Continue with clear, actionable steps.
    
    Each step should be independently verifiable.
  </Step>
  
  <Step title="[Final action]">
    Complete the task.
  </Step>
</Steps>

## Example

Complete working example showing the end result.

```language
// Full example code with all pieces together
```

## Variations

<Tabs>
  <Tab title="Option A">
    Alternative approach for specific use case.
  </Tab>
  <Tab title="Option B">
    Another variation.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="[Common issue]">
    **Problem:** Description of the issue.
    
    **Solution:** How to resolve it.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Related Guide" href="/path">
    Brief description of related task
  </Card>
  <Card title="Reference" href="/path">
    Deep dive into configuration options
  </Card>
</CardGroup>
```

## Guidelines

- **Start with the outcome** - readers should know what they'll achieve
- **Each step should be independently verifiable** - readers can check progress
- **Use action verbs** in step titles - "Configure", "Add", "Create", "Enable"
- **Include error handling** in code examples
- **Provide alternatives** when multiple approaches exist
- **Link to related guides** at the end
- **Use mermaid diagrams** to visualize complex flows
- **Keep diagrams simple** - max 7-10 nodes

## Diátaxis Principles for How-To Guides

| Principle | Application |
|-----------|-------------|
| Task-oriented | Focus on achieving a specific goal |
| Practical | Solves a real problem |
| Flexible | Can adapt to different contexts |
| Direct | Gets to the point quickly |
| Assumes competence | Reader knows the basics |

## Mermaid Diagram Types for How-To Guides

### Flowchart (for processes)
```mermaid
flowchart TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

### Sequence (for API calls)
```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Database
    
    Client->>API: POST /users
    API->>Database: INSERT user
    Database-->>API: user_id
    API-->>Client: 201 Created
```

### State (for status transitions)
```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: start
    Processing --> Completed: success
    Processing --> Failed: error
    Failed --> Processing: retry
    Completed --> [*]
```
