Documentation Writing Guidelines

Standards and best practices for writing API and integration documentation.

---

Table of Contents

1. Philosophy & Audience

2. Writing Guidelines

   • Voice & Tone

   • Language Rules

   • Formatting Discipline

   • The Two-Tier Content Model

   • Glossary Requirement

   • FAQ Structure

3. Visual Engagement Standards

   • Emoji Section Headers

   • TL;DR Boxes

   • Callouts

   • Quick Check Lists

   • Key Takeaway Boxes

   • Collapsible Sections

   • Use Case Cards

   • Emoji Reference

4. Document Structure

5. Diagram Standards

6. Technical Deep-Dive Format

7. Quality Checklist

---

Philosophy & Audience

Why These Docs Exist

These guides exist to empower external stakeholders to build integrations and workflows using our API. They should answer the question: "How can I use this to solve my problem?" — helping technical readers connect their systems to ours with confidence.

Target Audiences

Audience	What They Need	How They'll Use It
Integration Developers	Clear API contracts, examples, and workflow patterns	Building custom integrations, automating processes, connecting systems
Technical Administrators	Understand capabilities and configuration options	Setting up webhooks, managing API keys, configuring integrations
Solutions Architects	Understand how the API fits into their architecture	Planning integrations, evaluating capabilities, designing workflows
Technical Decision-Makers	Understand what's possible and the effort involved	Evaluating feasibility, scoping projects, making build vs. buy decisions

The Golden Rule

If a technically-minded non-engineer can't understand the main content, we've failed.

Deep implementation details are valuable, but they belong in clearly-marked sections — not scattered throughout the document. The goal is empowerment, not overwhelm.

Goals

1. Enable self-service integration — Readers can build working integrations without contacting support

2. Answer "how do I accomplish X?" — Practical guidance, not just reference material

3. Reduce time-to-integration — Clear examples and patterns accelerate implementation

4. Build confidence — Readers understand what to expect and how to handle edge cases

5. Support diverse technical backgrounds — Accessible to anyone comfortable with APIs, not just engineers

6. Inspire possibilities — Show what's achievable so readers can envision their own workflows

---

Writing Guidelines

Voice & Tone

• Conversational but professional — Write like you're explaining to a smart colleague, not writing a textbook

• Active voice — "The API returns a response" not "A response is returned by the API"

• Direct and concise — Get to the point; respect the reader's time

• Empowering — Focus on what the reader can accomplish, not limitations

• Empathetic — Anticipate confusion and address it proactively

Language Rules

✅ Do	❌ Don't
Use plain English for main content	Use jargon without explaining it first
Define technical terms when first introduced	Assume everyone knows what "webhook payload" means
Explain why something works a certain way	Only explain what happens
Use analogies for complex concepts	Dive straight into implementation details
Write "When you send a POST request..."	Write "When webhookHandler() processes the request..."
Focus on the reader's goal	Focus on internal implementation

Formatting Discipline

Bold text should be used intentionally to make points — not to randomly highlight words.

Less is more. When everything is emphasized, nothing is.

✅ Good Use of Bold	❌ Bad Use of Bold
Webhooks do not retry after a successful response.	Webhooks do not retry after a successful response.
The key point: events are delivered in order of creation.	The key point: events are delivered in order of creation.
Use bold for the single most important takeaway in a paragraph.	Use bold for every important-sounding word in a paragraph.

Guidelines:

• Bold the conclusion, not every step leading to it

• Bold terms being defined, not random nouns

• Bold warnings or critical info, not general statements

• If a sentence has more than one bold phrase, reconsider — pick the most important one

The Two-Tier Content Model

Every guide should have two tiers of content:

Tier 1: General Content (Everyone)

This is the main body of the document. It should be:

• Readable by technical non-engineers — An operations manager or solutions architect can understand it

• Outcome-focused — Explains what you can do and why it works this way

• Practical language — Uses API and workflow terminology, not internal code concepts

• Visually supported — Diagrams show flows and relationships

Example (General Content):

When an event occurs in your system, you can configure a webhook to notify our API automatically. The webhook sends a payload containing the event details, and our system processes it based on your configured rules.

Tier 2: Technical Deep-Dives (Developers)

Technical details are contained in clearly-marked sections. They should be:

• Visually distinct — Use a blockquote or callout format

• Skippable — Non-developer readers can skip without losing context

• Implementation-focused — Code samples, data structures, authentication details

• Precise — Include exact field names, data types, and expected formats

Format for Technical Sections:

> **🔧 Technical Deep-Dive: [Topic]**
>
> For developers implementing this integration:
>
> - The webhook payload must include a valid `X-Signature` header
> - Use HMAC-SHA256 to verify the signature against your secret
> - [Code example or detailed explanation]

Glossary Requirement

Every guide must include a Key Terms section near the top that defines domain-specific vocabulary in plain language. This ensures everyone starts with the same understanding.

Example:

Term	Definition
Webhook	An automated message sent from one system to another when an event occurs
Payload	The data included in a webhook or API request
Endpoint	A specific URL where your system receives or sends data
Subscription	A configuration that determines which events trigger webhooks

FAQ Structure

FAQs should be written from the integrator's perspective, not the internal engineer's:

✅ Good FAQ Question	❌ Bad FAQ Question
"Why isn't my webhook receiving events?"	"Why did webhookDispatcher fail to enqueue?"
"How do I verify a webhook signature?"	"How does HMAC validation work internally?"
"Can I filter which events trigger my webhook?"	"How do I configure event filtering in the database?"

---

Visual Engagement Standards

Documentation should be scannable and engaging — not a wall of text. Use these formatting patterns consistently across all guides:

1. Emoji Section Headers

Use emojis on major section headers for instant visual recognition:

## 🎯 Overview
## 📖 Key Terms  
## ⚙️ How It Works
## 💡 Key Concepts
## 📋 Common Scenarios
## ❓ FAQ
## 🔧 Technical Reference

2. TL;DR Boxes

Add a quick summary at the top of dense sections:

> **📌 TL;DR**
> 
> [1-3 sentence summary of the section for readers in a hurry]

3. Tip / Warning / Info Callouts

Use consistent emoji-prefixed blockquotes throughout:

> **💡 Tip:** [Helpful advice or shortcut]

> **⚠️ Warning:** [Common mistake or important caveat]

> **ℹ️ Note:** [Additional context that's good to know]

4. Quick Check Lists in FAQs

Make troubleshooting scannable with checkbox-style lists:

### ❓ "Why didn't X happen?"

**🔍 Quick Check:**
- ✅ Is the feature enabled?
- ✅ Does the user have permission?
- ✅ Is the configuration correct?

**📝 Full Answer:**
[Detailed explanation...]

5. Key Takeaway Boxes

End major sections with a highlighted takeaway:

> **🎯 Key Takeaway**
> 
> [The one thing readers should remember from this section]

6. Collapsible Technical Details

For deep technical content that most readers can skip (GitHub-flavored Markdown):

<details>
<summary>🔧 Technical Details (click to expand)</summary>

[Detailed implementation information...]

</details>

7. Use Case Cards

Make use cases visually distinct with summary tables:

### 📗 Use Case: [Name]

| | |
|---|---|
| **Goal** | What you're trying to accomplish |
| **How** | The approach to achieve it |
| **Result** | What happens when successful |

**Step-by-step:**
1. ...

Standard Emoji Reference

Use these emojis consistently across all documentation:

Emoji	Usage
🎯	Overview sections, key takeaways
📖	Key terms / glossary
⚙️	How it works / mechanics
💡	Key concepts, tips
📋	Use cases, examples
❓	FAQ sections
🔧	Technical reference, deep-dives
📌	TL;DR summaries
⚠️	Warnings, common mistakes
ℹ️	Notes, additional context
✅	Checklist items, do's
❌	Don'ts, failures
📗	Positive use case (success path)
📙	Neutral use case (alternative path)
📕	Negative use case (error/edge case)
🔍	Quick check / diagnosis
📝	Detailed explanation
👤	Audience indicator (General)
👩‍💻	Audience indicator (Developers)

---

Document Structure

Each guide follows a consistent structure designed for multiple audiences:

# [Feature/API] Guide

[One-line description of what this guide covers]

---

## Table of Contents

## 🎯 Overview

> **📌 TL;DR**
> 
> [1-3 sentence summary for readers in a hurry]

- One-paragraph summary anyone can understand
- What problem this solves for integrators
- What you can accomplish with it

## 📖 Key Terms
- Glossary table of domain vocabulary
- Plain-language definitions

## ⚙️ How It Works
- Conceptual explanation with diagrams
- Written for general audience
- Answers: "What happens when...?"

> **🎯 Key Takeaway**
> 
> [The one thing to remember from this section]

## 💡 Key Concepts
### [Concept 1]
- Explanation in practical terms
- When/why it matters for your integration
- > 🔧 Technical Deep-Dive (optional)

### [Concept 2]
- Same pattern...

## 📋 Common Use Cases

### 📗 Use Case: [Success Path]

| | |
|---|---|
| **Goal** | What you're trying to accomplish |
| **How** | The approach to achieve it |
| **Result** | What happens when successful |

### 📕 Use Case: [Edge Case / Error Handling]
- Same pattern...

## ❓ FAQ

### ❓ "[Question from integrator's perspective]"

**🔍 Quick Check:**
- ✅ First thing to verify
- ✅ Second thing to verify

**📝 Full Answer:**
[Detailed explanation...]

## 🔧 Technical Reference
- This entire section is for developers
- API endpoints, authentication details
- Request/response schemas, code examples

---

*Last updated: [Date]*

---

Diagram Standards

Diagrams should be understandable without reading surrounding text.

Requirements:

• Use descriptive labels, not technical names

• Include a brief caption explaining what the diagram shows

• Use ASCII art for compatibility (renders in GitHub, Slack, etc.)

Example:

How Webhook Delivery Works
──────────────────────────

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Event     │────▶│   Webhook   │────▶│    Your     │
│   occurs    │     │   created   │     │   system    │
│  in system  │     │  & queued   │     │  receives   │
└─────────────┘     └─────────────┘     └─────────────┘

Tips for ASCII diagrams:

• Use box-drawing characters: ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼

• Use arrows: → ← ↑ ↓ ▶ ◀ ▲ ▼ or ──▶

• Keep labels short and clear

• Test rendering in GitHub preview

---

Technical Deep-Dive Format

All technical content should be contained in clearly-marked sections:

> **🔧 Technical Deep-Dive: Webhook Signature Verification**
>
> To verify the webhook signature in your handler:
>
> ```javascript
> const crypto = require('crypto');
> 
> function verifySignature(payload, signature, secret) {
>   const expected = crypto
>     .createHmac('sha256', secret)
>     .update(payload)
>     .digest('hex');
>   return crypto.timingSafeEqual(
>     Buffer.from(signature),
>     Buffer.from(expected)
>   );
> }
> ```
>
> Key considerations:
> - Always use timing-safe comparison to prevent timing attacks
> - The signature is computed on the raw request body

This format:

• Is visually distinct (blockquote + emoji)

• Can be skipped by non-developer readers

• Provides working code examples for those implementing integrations

---

Quality Checklist

Use this checklist when writing or reviewing documentation:

Accessibility (Required)

• A technical non-engineer can understand the Overview section

• Key Terms glossary defines all jargon

• Main content focuses on what the reader can accomplish

• FAQ questions are written from integrator's perspective

• Diagrams have descriptive labels and captions

Technical Depth (Required)

• Technical deep-dives include working code examples

• API references include request/response schemas

• Code examples are copy-paste ready and correct

• Error handling and edge cases are documented

Completeness

• FAQ addresses common integration questions

• Common use cases cover 80% of real-world scenarios

• Troubleshooting guidance is included (what to check when things go wrong)

• Authentication and security requirements are clearly explained

Formatting

• Uses consistent emoji headers

• Includes TL;DR for dense sections

• Bold text used sparingly and intentionally

• Two-tier model followed (general content + technical deep-dives)

---

Contributing

When you find something that could be improved:

• Quick fixes: Open a PR with your change

• Missing content: Create a GitHub issue tagged documentation

• New guide needed: Follow this guide's structure template

---

These guidelines help us maintain documentation that empowers technical stakeholders to build integrations and workflows with confidence.