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

# Writing playbook

> Voice, structure, and review standards for Handa Uncle docs

## Audience & voice

| Segment              | What they need                                   | Voice                        |
| -------------------- | ------------------------------------------------ | ---------------------------- |
| Mobile engineers     | Exact headers, auth flows, and expected payloads | Direct, imperative           |
| Backend contributors | Architectural context + invariants               | Concise, technical           |
| Operations/support   | Runbooks, alert context, SLAs                    | Actionable, checklist-driven |

* Write in second person when giving instructions (“You can verify…“).
* Prefer active voice and present tense.
* Lead with the answer, follow with supporting detail (inverted pyramid).

## Page skeleton

Every MDX document starts with frontmatter:

```md theme={null}
---
title: 'Clear, keyword-rich headline'
description: 'Why the page exists in one sentence'
---
```

Follow with this flow:

1. **Context** – one paragraph describing the problem.
2. **Prerequisites** – tooling, accounts, permissions.
3. **Procedure / reference** – headings with numbered steps or tables.
4. **Verification** – commands or response snippets that prove success.
5. **Next steps / troubleshooting** – optional, but encouraged for ops-heavy docs.

## Formatting patterns

* Use `##` for top-level sections (Mintlify adds `#` automatically in the hero).
* Convert long explanations into tables where possible (see env + command tables
  elsewhere in the docs).
* Keep lists parallel; each bullet should start with the same part of speech.
* Prefer `<Steps>`, `<AccordionGroup>`, and `<CardGroup>` over deep heading
  nesting when the content benefits from progressive disclosure.

## Linking + references

* Internal links should be absolute from the docs root:
  `[App launch](/api-reference/endpoint/app-launch)`.
* Link to source files in GitHub when describing implementation details, e.g.
  `src/services/app/services/app-launch.service.ts`.
* When referencing root-level design docs, use the GitHub URL so the links work
  inside the hosted docs site.

## Review checklist

<Checklist>
  <Check>Does the title/description match the actual scope?</Check>
  <Check>Are commands, cURL examples, and JSON responses copy-paste ready?</Check>
  <Check>Does the page mention where to find more detail (code path or design doc)?</Check>
  <Check>Did you add a verification step or expected output?</Check>
</Checklist>