Seu README matou seu agente (docs que falham)

Seu README matou seu agente (docs que falham)

Notícia: Dev pagou pessoas pra testar seu README (instruções de como usar projeto). Resultado: 50%+ FALHARAM ao seguir instruções. Implicação: Se instruções de um projeto simples falham em 50% das pessoas, SUAS INSTRUÇÕES DE AGENTE (muito mais complexas) provavelmente falham em 70-80%.

Problema: Seu agente tá lindamente construído. Mas documentação? Ruim. Customer tenta integrar agente (seguindo seu README). Falha em primeira instrução. Tenta novamente. Falha de novo. Customer pensa: "Este produto é ruim." Customer cancela. Você perdeu cliente (não por culpa do agente, mas por culpa da documentação).

Implicação: Documentação RUIM = Agente APARENTEMENTE ruim (mesmo que funcione perfeitamente). Você precisa entender: Como escrever docs que pessoas REALMENTE conseguem seguir (não docs que VOCÊ ACHA que é claro, mas que ninguém entende).

Problema: Seu README provavelmente falha assim:

WHAT DEVELOPERS THINK THEY WROTE (in README): ├─ "Install dependencies: npm install" ├─ "Configure API key: export API_KEY=your_key" ├─ "Run server: npm start" ├─ "Done! Your agente is running." └─ (Looks clear, right?)

WHAT CUSTOMERS ACTUALLY ENCOUNTER: ├─ "npm install" - Which directory? (Customer confused) ├─ "export API_KEY=your_key" - Where do I get API_KEY? (Not explained) ├─ "npm start" - What if I get an error? (No error handling docs) ├─ Customer: "It says 'port 3000 already in use', now what?" ├─ Customer: "Your docs don't cover this!" ├─ Customer: "Forget it, using competitor instead" └─ You lose customer (docs failed)

STATISTICS (from the study): ├─ 50% couldn't follow README ├─ Reasons: Unclear instructions, missing steps, no error handling ├─ Implication: Even simple docs fail ├─ Your docs: 3x more complex = 70-80% failure rate ├─ Impact: Massive churn (customers can't integrate) └─ Lesson: Docs are CRITICAL (not "nice to have")

THE CYCLE: ├─ You build: Amazing agente (works great) ├─ You write: README (looks good to you) ├─ Customer tries: Integration (follows README) ├─ Customer fails: "Can't get it working" (README missing step) ├─ Customer support: "Your docs are unclear" (frustration) ├─ You discover: Step 3 was confusing ├─ You fix: README (now even longer) ├─ Customer 2 tries: Different error (still stuck) ├─ Customer 2 leaves: "Too complicated" (even though it's simple) └─ Result: Good agente, bad docs = dead product

---

Entender: Por que docs falham

The curse of knowledge

THE PROBLEM: ├─ You know: Every step of integration (you built it) ├─ You forget: Customer doesn't know ANYTHING ├─ You write: "Configure your API" (vague) ├─ Customer thinks: "Which API? Where?" ├─ Result: Failure (step too unclear) └─ Why: You have "curse of knowledge" (can't unthink what you know)

EXAMPLE: ├─ You write: "Set up authentication" ├─ You mean: "Create OAuth app in Stripe dashboard, copy secret, paste in .env as STRIPE_SECRET" ├─ Customer reads: "Set up authentication" (incomplete!) ├─ Customer thinks: "How? What authentication? Which service?" ├─ Customer doesn't find answer (docs don't explain) ├─ Customer gets stuck └─ Result: Failure (you were too brief, they didn't know)

THE FIX: ├─ Write: Assuming customer knows NOTHING ├─ Be explicit: Every step, every detail ├─ Include: Screenshots (visual guidance) ├─ Include: Copy-paste examples (reduce guessing) ├─ Include: Error handling ("if you see X, do Y") ├─ Include: Validation ("verify it works by running Z") └─ Result: Customer succeeds (even without your knowledge)

MENTAL MODEL: ├─ Your mental model: "API setup is 2 clicks" (for you) ├─ Customer mental model: "I don't know where to start" (first time) ├─ Your docs: "Do API setup" (you = 2 clicks, they = lost) ├─ Better docs: "Click Services → Create App → Copy secret" (step-by-step) └─ Result: Same task, but docs explain THEIR journey, not YOUR knowledge

The study findings

WHAT THE STUDY SHOWED: ├─ 50% of people couldn't follow README ├─ Even for relatively simple projects ├─ Even when they had technical background ├─ Even when they were motivated (paid to test) └─ Implication: Docs are REALLY hard to write clearly

WHY PEOPLE FAILED: ├─ Missing steps (docs skipped something) ├─ Unclear wording ("configure X" = what does that mean?) ├─ No error handling ("if you get error Y, here's the fix") ├─ No validation ("verify it works by doing Z") ├─ Outdated info ("use Node 12" but customer has Node 18 = breaks) ├─ Platform assumptions ("on Mac, do X" but customer on Windows) ├─ Missing dependencies ("npm install" but didn't mention Node.js) └─ Screenshot/context missing ("the button in the left panel" = which panel?)

THE COST: ├─ 50% failure = 50% of customers can't use your product ├─ Those customers: Churn (use competitor instead) ├─ Those customers: Bad reviews ("product doesn't work") ├─ Those customers: Tell friends (negative word-of-mouth) ├─ Actual impact: 50% churn on integration = DEATH for SaaS ├─ Your agente: Works perfectly, but appears broken (because docs broken) └─ Lesson: Docs = product (if docs broken, product is broken)

---

Como escrever docs que funcionam

Strategy 1: Write for the beginner (not yourself)

IDEIA: ├─ Forget what you know ├─ Write for: Someone who knows NOTHING ├─ Include: Every single step (no assumptions) ├─ Test: Have someone with zero knowledge follow docs ├─ Result: Docs that actually work └─ Why: If beginner succeeds, expert will succeed (not vice versa)

IMPLEMENTATION:

Step 1: Identify your beginner ├─ Who: First-time user of your agente ├─ What they know: Nothing (assume zero) ├─ What they want: Get agente working (ASAP) ├─ What they fear: "I'll break something" (they're nervous) └─ Strategy: Docs should be beginner-proof

Step 2: Write step-by-step (like a recipe) ├─ NOT: "Install dependencies" ├─ BUT: "Open terminal. Type: npm install. Press Enter. Wait 2 minutes." │ ├─ NOT: "Configure API key" ├─ BUT: "Go to https://api.openai.com. Click Account → API Keys. Click Create Key. Copy the key. Open .env file. Find the line API_KEY=. Replace with your key. Save file." │ ├─ NOT: "Run the server" ├─ BUT: "Type: npm start. You should see 'Server running on port 3000'. If you see that, it worked." │ └─ Style: Simple, concrete, specific (not abstract)

Step 3: Include screenshots (visual = clearer) ├─ For each major step: Take screenshot ├─ Show: Exactly what they should see ├─ Highlight: The button to click (circle it, arrow it) ├─ Caption: "Click here. You should see this." └─ Benefit: Visual reduces guessing (they can compare with their screen)

Step 4: Handle errors ("if X, do Y") ├─ Include: Common errors ├─ For each error: Explain why it happens ├─ For each error: Provide exact fix │ ├─ Example: │ ├─ "Error: Port 3000 already in use" │ ├─ Why: Another app is using port 3000 │ ├─ Fix: Kill other app: lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill │ └─ Then: Try npm start again │ └─ Benefit: Customer doesn't get stuck on first error

Step 5: Include validation ("you'll know it worked when...") ├─ After each step: Explain what success looks like ├─ Example: "If installation worked, you'll see 'added 1,245 packages in 45 seconds'" ├─ Example: "If agente is running, you'll see 'Listening on port 3000'" ├─ Benefit: Customer knows they're on the right track └─ Reduces: "Is this working? Did I do it right?" confusion

Step 6: Verify with user testing ├─ Before launch: Have someone unfamiliar read docs ├─ Watch them: Try to follow your instructions ├─ Note: Where they get stuck (that's broken docs) ├─ Fix: Every place they were confused ├─ Test again: Verify they can now succeed └─ Benefit: You catch gaps BEFORE customers get frustrated

EXAMPLE (BAD docs vs GOOD docs):

BAD README:

Installation

1. Clone repo
2. Install dependencies
3. Configure environment
4. Run agente

GOOD README:

Installation (Step by step)

Step 1: Clone the repository

Open terminal (Mac/Linux) or PowerShell (Windows). Type this command and press Enter: bash git clone https://github.com/yourname/agente.git cd agente

You should see a folder called "agente" opened in your terminal.

Step 2: Install dependencies

Type this command and press Enter: bash npm install

This will download ~1,200 packages (takes 2-5 minutes). When done, you'll see "added 1,245 packages in 45 seconds".

If you get an error:

• Error: "npm: command not found" → You don't have Node.js installed. Download here
• Error: "Permission denied" → Try: sudo npm install (then enter your password)

Step 3: Configure environment

Create a file called .env in the agente folder:

Open folder in code editor (VS Code recommended):

• Right-click agente folder → Open with Code
• In VS Code, create new file: Ctrl+N
• Paste this content:

OPENAI_API_KEY=your_key_here PORT=3000

• Go to https://openai.com → Login → API Keys → Create new
• Copy your API key
• Replace "your_key_here" with your actual key
• Save file (Ctrl+S)

Step 4: Run the agente

In terminal, type: bash npm start

Success looks like:

✓ Server running on http://localhost:3000 ✓ Agente initialized ✓ Ready for requests

If you see this, your agente is working! 🎉

If you get an error:

• Error: "Cannot find module 'express'" → Run npm install again (step 2)
• Error: "Port 3000 already in use" → Another app is using your port. Kill it: lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill
• Error: "OPENAI_API_KEY is undefined" → Check your .env file (step 3) has the key

Verify it works

Open your browser, go to http://localhost:3000 You should see the agente dashboard.

Congratulations! Your agente is running. 🚀

Difference: ├─ BAD: 4 lines (assumes you know everything) ├─ GOOD: 100 lines (explains everything, handles errors) ├─ BAD: 50% will fail (too vague) ├─ GOOD: 90%+ will succeed (step-by-step, error handling) └─ Length: Worth it (saves 50% of support tickets)

Strategy 2: Test with real users before launch

IDEIA: ├─ Don't assume docs are clear (they usually aren't) ├─ Test: Have unfamiliar person follow docs ├─ Watch: Where they get confused ├─ Fix: Every gap they find ├─ Repeat: Until they succeed (then docs are ready) └─ Cost: 2 hours testing = saves 100s of support tickets

IMPLEMENTATION: ├─ Step 1: Pick tester │ ├─ Who: Someone who's never used your agente │ ├─ Ideally: Different experience level (beginner + intermediate) │ ├─ Can pay: A bit ($50-100) to make it worth their time │ └─ Why: They'll be honest (and represent real customers) │ ├─ Step 2: Give them README + agente │ ├─ Say: "Here's the docs. Try to get agente working." │ ├─ Don't help: Let them struggle (that's the point) │ ├─ Watch: Where they get stuck (screenshot/note it) │ ├─ Record: Every question they ask │ └─ Goal: Identify gaps in docs │ ├─ Step 3: Note all failures │ ├─ Failure 1: "Where do I get the API key?" → Docs missing this detail │ ├─ Failure 2: "What does 'configure environment' mean?" → Too vague │ ├─ Failure 3: "I got an error, but docs don't explain what to do" → Missing error handling │ ├─ Failure 4: "Which folder do I run npm install in?" → Unclear wording │ └─ Each failure = docs need fix │ ├─ Step 4: Update docs │ ├─ For each failure: Add detail to docs │ ├─ Make it: So clear that next tester won't fail │ ├─ Add: Screenshots where helpful │ ├─ Add: Error handling for common mistakes │ └─ Test: Read new docs yourself (verify it's better) │ ├─ Step 5: Test again (with different person) │ ├─ Give: Updated README to new tester │ ├─ Watch: Where they get stuck (should be fewer places) │ ├─ If they succeed: Docs are ready! │ ├─ If they fail: Fix those gaps too │ └─ Repeat: Until success rate is 90%+ │ └─ Timeline: 1-2 weeks (worth it)

EXAMPLE: ├─ You write: "Configure environment" ├─ Tester asks: "Which environment? What config? Where do I do this?" ├─ You realize: This sentence means nothing without context ├─ You rewrite: "Create a .env file (in the agente folder)...[full explanation]..." ├─ Tester 2: Follows new docs successfully └─ Result: One gap fixed, 100% success (instead of 50% confusion)

Strategy 3: Keep docs updated

IDEIA: ├─ Docs get old (version changes, API updates) ├─ Old docs = broken docs = customers can't follow ├─ Keep updated: When agente changes, update docs immediately ├─ Version: Docs with agente version ("docs for v1.2.0") └─ Benefit: Customers always have correct docs

IMPLEMENTATION: ├─ When you update agente: │ ├─ Also update: README + all docs │ ├─ Note: What changed ("In v1.2.0, we renamed X to Y") │ ├─ Update: All examples (use new syntax) │ ├─ Update: Screenshots (if UI changed) │ └─ Test: Run through docs again (verify still work) │ ├─ Version your docs: │ ├─ Tag: "README for v1.2.0" │ ├─ Archive: Old docs (customers on old version can find them) │ ├─ Link: "Using older version? View v1.1 docs here" │ └─ Benefit: Customers know docs are for their version │ └─ Regular maintenance: ├─ Monthly: Review docs for outdated info ├─ Quarterly: Test docs with new user (verify still clear) ├─ When customer asks: "How do I X?" → Add to FAQ in docs └─ Result: Docs stay fresh, customers stay happy

---

Conclusão: Docs are product

Fatos:

✓ Study showed: 50% of people can't follow README ✓ Your docs: Probably worse (agente more complex than typical project) ✓ Failure = churn: Customer can't integrate = uses competitor instead ✓ Solution 1: Write for beginner (not yourself) ✓ Solution 2: Test with real user (before launch) ✓ Solution 3: Keep docs updated (when agente changes) ✓ Screenshots: Essential (visual guidance matters) ✓ Error handling: Critical ("if you see error X, do Y") ✓ Validation: Important ("you'll know it worked when...") ✓ Step-by-step: Required (don't assume anything) ✓ Clarity: Above all (simple > fancy) ✓ Investment: 2 weeks on docs = saves 1000s of support hours

ACTION ITEMS (IMMEDIATE):

1. TODAY: Read your README with fresh eyes
2. TODAY: Ask: "Would a beginner understand this?"
3. WEEK 1: Add missing details (every step explicit)
4. WEEK 1: Add screenshots (visual guidance)
5. WEEK 1: Add error handling ("if X, do Y")
6. WEEK 2: Find tester (someone unfamiliar with agente)
7. WEEK 2: Watch them follow docs (note where they fail)
8. WEEK 2: Fix every gap they found
9. WEEK 3: Test with different person (verify success)
10. ONGOING: Update docs when agente changes

Problema resolvido quando: └─ README: So clear that beginners understand └─ Screenshots: Show exactly what they should see └─ Error handling: Covers common mistakes └─ Validation: Tells them when they succeeded └─ User test: 90%+ people can follow without help └─ Result: Customers integrate agente smoothly └─ Churn: Drops (not because agente is better, but docs are clearer) └─ Support: Tickets drop (docs answer questions) └─ Product: Appears better (because docs make it easy)

→ OpenClaw: Agentes com Documentação Clara + User Testing

Dev pagou pessoas pra testar README: 50% falharam. Seu agente? Docs quebradas = customers desistem. Escreva para iniciante (não pra você). Teste com usuário real. Adicione screenshots + tratamento de erros. Atualize quando agente muda. Docs claras = agente parece melhor. 📖