Update kb/kb_best_practices.md

kb/kb_best_practices.md

@@ -1,121 +1,62 @@
-# 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
+# 📘 1. What Makes an Excellent Knowledge Base Article
+---
 
-Start each knowledge base article with a short paragraph that explains:
 
-- What the article covers  
-- When to use it  
-- Any prerequisites  
+## 4. Use a Support-Friendly Tone
 
-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.”
+Tone should feel:
+- Friendly
+- Confident
+- Supportive
 
-This gives context and reduces confusion.
 
-## 4. Step-by-step instructions with actions and results
+**Good:** “Let’s walk through how to reset your password.”
 
-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
+**Not so good:** “Resetting a password requires following the steps below.”
 
-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
+## 5. Test Before Publishing
 
-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
+Ensure someone else:
+- Follows the steps
+- Tests the flow
+- Flags unclear phrasing
 
-Example:
 
-> **Note:** If you already have this number connected in another tool, you may need to disconnect it there before connecting it here.
+Writers are often too close to see gaps.
 
-## 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  
+## 6. Keep It Short — But Complete
 
-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.
+Balance:
+- **Minimalism** (no fluff)
+- **Completeness** (no missing steps)
 
-## 7. Keep tone simple, friendly, and consistent
 
-Use:
+Provide just enough context for understanding.
 
-- 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:
+## 7. Evolve With Product Changes
 
-- Review regularly after product changes
-- Update screenshots and steps when the UI changes
-- Remove or merge duplicated content
-- Mark deprecated features clearly
 
----
+Update articles when:
+- UI changes
+- Buttons are renamed
+- Policies shift
+- Processes change
 
-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 
+A KB is a living system.