Create kb/kb_best_practices.md

kb/kb_best_practices.md

@@ -0,0 +1,121 @@
+# What makes a good knowledge base article?
+
+A good knowledge base article is one that helps the reader solve a problem quickly, confidently, and without needing extra help. It should be clear, structured, and written from the user’s perspective, not from the internal product or team perspective.
+
+Below are the key elements that make a knowledge base article effective.
+
+## 1. Clear purpose and audience
+
+Before writing, define:
+
+- **Who** is this for? (customer, agent, admin, partner)
+- **What problem** does it solve?
+- **What outcome** should the reader achieve after following it?
+
+A good rule of thumb is:  
+> *“If I read this article, can I answer ‘what should I do next?’ at every step?”*
+
+## 2. Descriptive title that matches user wording
+
+The title should match the language users would actually search for, not internal jargon.
+
+**Good examples:**
+
+- “How to connect WhatsApp to your workspace”
+- “Troubleshooting Instagram connection errors”
+- “How to build your first automation flow”
+
+**Avoid:**
+
+- “Channel integration v2”
+- “Internal setup guide”
+
+If users cannot guess what the article contains from the title, they are less likely to click it.
+
+## 3. Short overview at the top
+
+Start each knowledge base article with a short paragraph that explains:
+
+- What the article covers  
+- When to use it  
+- Any prerequisites  
+
+Example:
+
+> “This article shows you how to connect WhatsApp to your workspace so you can send and receive messages from your customers. You’ll need an active WhatsApp Business number and admin access to your workspace.”
+
+This gives context and reduces confusion.
+
+## 4. Step-by-step instructions with actions and results
+
+Good steps are:
+
+- Written in **imperative form** (e.g. “Click…”, “Open…”, “Select…”)
+- Only contain **one action per step**
+- Include **what the user should see** after the step, if it’s important
+
+Example structure:
+
+1. Go to **Settings → Channels → WhatsApp**.  
+2. Click **Connect WhatsApp**.  
+3. Follow the on-screen instructions to sign in with your WhatsApp Business account.  
+4. When the connection is successful, you’ll see the status **Connected**.
+
+Where possible, pair steps with **screenshots** or short GIFs.
+
+## 5. Use headings, lists, and callouts
+
+Most readers scan, they do not read every word. Use:
+
+- Headings for sections like “Before you start”, “Steps”, “Common errors”
+- Bulleted lists for conditions or options
+- Numbered lists for procedures
+- Callouts or notes for important warnings or tips
+
+Example:
+
+> **Note:** If you already have this number connected in another tool, you may need to disconnect it there before connecting it here.
+
+## 6. Include common errors and how to fix them
+
+The best knowledge base articles anticipate what might go wrong.
+
+Add a **“Troubleshooting”** or **“Common issues”** section at the end with:
+
+- The error message or symptom  
+- Why it happens  
+- How to resolve it  
+
+Example:
+
+> **Error:** “Number linked elsewhere”  
+> **Why it happens:** Your phone number is still connected to another WhatsApp Business provider.  
+> **How to fix it:** Disconnect the number from the previous provider, wait 10–15 minutes, then try connecting again.
+
+## 7. Keep tone simple, friendly, and consistent
+
+Use:
+
+- Short sentences  
+- Neutral, supportive tone  
+- “You” and “we” rather than passive constructions  
+
+Avoid internal abbreviations and product code names. The reader should never feel like they are reading internal documentation.
+
+## 8. Review, maintain, and retire
+
+A good article is maintained over time:
+
+- Review regularly after product changes
+- Update screenshots and steps when the UI changes
+- Remove or merge duplicated content
+- Mark deprecated features clearly
+
+---
+
+When in doubt, a good knowledge base article should:
+
+- Be easy to find  
+- Be easy to scan  
+- Be easy to follow  
+- Solve the reader’s problem without needing a support ticket