1+ ## Purpose
2+
3+ Provide developers with documentation that is quick to read, easy to follow, and immediately actionable.
4+ Each page should meet the following principles:
5+
6+ | Principle | Description |
7+ | -------------------- | ------------------------------------------------------------- |
8+ | **Clarity** | Use plain language—avoid jargon or unnecessary complexity. |
9+ | **Brevity** | Keep sentences and paragraphs short. |
10+ | **Task‑orientation** | Present steps in a logical order that help the reader proceed.|
11+ | **Scannability** | Apply headings, spacing, and components that aid quick review.|
12+ | **Outcome focus** | Ensure every section directly supports the user’s success. |
13+
14+ ---
15+
16+ ## Style rules
17+
18+ - **Titles**: Capitalize only the first word unless a proper noun is used.
19+ *Examples*: `Getting started`, `Voice AI`, `API reference`
20+ - **Subtitles**: Begin with *Learn to …* for guides; otherwise keep them concise and factual.
21+ - **Emojis / decorative icons**: Use only when essential for comprehension.
22+ - Tone: Direct, professional, friendly.
23+ - Break up large blocks of text with line‑breaks.
24+ - Avoid marketing or promotional wording.
25+ - Link to related pages when helpful, especially the **API reference** at `/fern/api-reference`.
26+ - Use **bold** text to emphasize key names or concepts.
27+
28+ ### Writing style & tone
29+
30+ | Guideline | Why it matters |
31+ |-----------|---------------|
32+ | **Active voice** | “Connect the SDK” is clearer than “The SDK should be connected.” |
33+ | **Present tense** | Keeps instructions straightforward (e.g., “Run” not “You will run”). |
34+ | **Second‑person (“you”)** | Speaks directly to the reader. Reserve “we” for collaborative tutorials. |
35+ | **Explain intent before action** | Briefly state *why* a step is needed, then show *how*. |
36+ | **Concrete examples over theory** | Code snippets and visuals anchor concepts. |
37+ | **Consistent terminology** | Define a term once; reuse it exactly the same everywhere. |
38+ | **Parallel structure** | Lists and headings should follow consistent grammatical patterns. |
39+ | **Descriptive link text** | Use “view the guide” rather than “click here.” |
40+ | **Comment code sparsely** | Only where intent isn’t obvious from variable/function names. |
41+
42+ > **Rule of thumb**: every sentence should either clarify *why* or *how*—if it does neither, remove or rewrite it.
43+
44+ ---
45+
46+ ## MDX front‑matter template
47+
48+ ```mdx
49+ ---
50+ title: <short title>
51+ subtitle: <concise subtitle>
52+ ---
53+ ```
54+
55+ ### Sample titles
56+
57+ - Getting started
58+ - Assistants
59+ - Variables
60+
61+ ### Sample subtitles
62+
63+ - Build a voice assistant that answers questions about your docs
64+ - Personalize assistant messages with dynamic and default variables
65+
66+ ---
67+
68+ ## Asset conventions
69+
70+ All images are stored in `/fern/static/images` (top‑level, not nested).
71+ Reference images with:
72+
73+ ```mdx
74+ 
75+ ```
76+
77+ ---
78+
79+ ## Recommended components
80+
81+ ### Accordions *(FAQ sections only)*
82+
83+ ```mdx
84+ <AccordionGroup>
85+ <Accordion title="Question 1">Answer</Accordion>
86+ </AccordionGroup>
87+ ```
88+
89+ ### Callouts
90+
91+ ```mdx
92+ <Tip>Helpful tip</Tip>
93+ <Note>Important note</Note>
94+ <Warning>Important caution</Warning>
95+ <Error>Possible error</Error>
96+ <Info>Additional information</Info>
97+ <Check>Successful outcome</Check>
98+ ```
99+
100+ ### Cards & Card groups
101+
102+ ```mdx
103+ <Card title="Python" icon="brands python" href="https://github.com/VapiAI/server-sdk-python">
104+ View Vapi’s Python server SDK.
105+ </Card>
106+ ```
107+
108+ ### Code snippets
109+
110+ ```javascript maxLines=10 wordWrap
111+ console.log('Hello, world');
112+ ```
113+
114+ ### Multi‑language code blocks
115+
116+ ```mdx
117+ <CodeBlocks>
118+ ```python title="hello.py"
119+ print("Hello")
120+ ```
121+ ```javascript title="hello.js"
122+ console.log("Hello")
123+ ```
124+ </CodeBlocks>
125+ ```
126+
127+ ### Step lists
128+
129+ ```mdx
130+ <Steps>
131+ <Step title="First step">Do this.</Step>
132+ <Step title="Second step">Do that.</Step>
133+ <Step title="Third step">Finished.</Step>
134+ </Steps>
135+ ```
136+
137+ ### Frames for images
138+
139+ ```mdx
140+ <Frame caption="Mountain range">
141+ <img src="/assets/images/mountains.jpg" alt="Mountains" />
142+ </Frame>
143+ ```
144+
145+ ### Tabs
146+
147+ ```mdx
148+ <Tabs>
149+ <Tab title="First">Content A</Tab>
150+ <Tab title="Second">Content B</Tab>
151+ </Tabs>
152+ ```
153+
154+ ---
155+
156+ ## Documentation sections & best practices
157+
158+ Drawing from Chris Nicholas’ *How to Write Exceptional Documentation* (Mar 2025), structure docs into purposeful sections so every developer quickly finds the right depth of information.
159+
160+ ### Quickstart
161+
162+ | Objective | Get a new user to a “Hello World” moment fast |
163+ |-----------|----------------------------------------------|
164+ | **Scope** | Only the minimal steps required; one guide per supported tech |
165+ | **Tips** | • Use numbered steps and visuals
166+ • Pre‑fill API keys where possible
167+ • Test end‑to‑end after every edit |
168+
169+ ### Tutorials
170+
171+ Teach broader concepts by **building something tangible** together.
172+ - Progressively increase complexity.
173+ - Add interactive elements (live code, mini‑quizzes).
174+ - Highlight best practices and link to deeper docs.
175+
176+ ### How‑to Guides
177+
178+ Solve a **specific problem** for existing users.
179+ - State the goal up front and list prerequisites.
180+ - Derive topics from recurring support questions.
181+ - Link to sample repos when helpful.
182+
183+ ### Explanations
184+
185+ Explain concepts, architecture, or reasoning.
186+ - Use diagrams and succinct prose—keep marketing out.
187+ - Include basic code when it clarifies the concept.
188+
189+ ### API Reference
190+
191+ Exhaustive, factual details for each endpoint / method.
192+ - Lead with the simplest usage pattern.
193+ - Use props / args / returns tables.
194+ - Anticipate errors and include handling guidance.
195+ - Cross‑link abundantly and follow familiar REST / OpenAPI layouts where applicable.
196+
197+ ### Examples
198+
199+ Small, focused demos that show how to implement one feature.
200+ - Display copy‑pasteable code.
201+ - Provide live, interactive previews when feasible.
202+
203+ ### Templates
204+
205+ Full, production‑ready starter projects.
206+ - Follow industry best practices and heavy inline commenting.
207+ - Offer one‑click deploy or CLI installers.
208+ - Use templates as reference material and marketing demos.
209+
210+ > **Iterate continuously.** Listen to user feedback and refine each section; great docs emerge through constant improvement.
211+
212+ ---
213+
214+ ## Example page skeleton
215+
216+ ```mdx
217+ ---
218+ title: Voice AI
219+ subtitle: Learn how to build and deploy voice agents with Vapi.
220+ ---
221+
222+ ## Overview
223+
224+ Vapi [Voice AI](/docs/assistants) enables you to build conversational agents for phone, web, and other platforms.
225+
226+ - Automate outbound support and sales
227+ - Integrate with your CRM
228+ - Deploy on phone, web, or mobile
229+
230+ For details, see **Assistants**.
231+
232+ ## Parameters
233+
234+ | Name | Purpose |
235+ | ---------------- | --------------------------------------- |
236+ | `model` | LLM used for conversations |
237+ | `voice` | Voice profile for the agent |
238+ | `knowledge_base` | Documents and data for context |
239+ | `tools` | Integrations and actions the agent uses |
240+
241+ ## FAQ
242+
243+ <AccordionGroup>
244+ <Accordion title="How do I create an assistant?">
245+ Visit the [Assistants](/docs/assistants) page and follow the guide.
246+ </Accordion>
247+ </AccordionGroup>
248+ ```
249+
250+ ---
0 commit comments