Skip to content

Commit 0337c2e

Browse files
goosewingoosewin
committed
Merge branch 'main' into feature/web-sdk-quickstart
2 parents 26591be + 607eeb3 commit 0337c2e

39 files changed

+7335
-1497
lines changed

‎.cursorrules‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
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+
![alt‑text](/assets/images/<file‑name>.<ext>)
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

Comments
 (0)