Writing playbook

​

Audience & voice

• 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

---
title: 'Clear, keyword-rich headline'
description: 'Why the page exists in one sentence'
---

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