Skip to main content

Troubleshooting section exists

ab-001007 · developer-documentation.content-quality.troubleshooting
Severity: lowactive

Why it matters

When the same question surfaces repeatedly in GitHub issues, Discord, or Stack Overflow and never lands in your docs, every maintainer hour spent re-answering it is a recurring tax. Users who hit a setup error without a troubleshooting entry either open a duplicate issue (inflating support load) or abandon the project silently. Documented troubleshooting converts recurring pain points into self-service, reducing issue volume and improving time-to-first-success for new users.

Severity rationale

Low because absent troubleshooting scales support cost but does not block a careful user.

Remediation

Add a ## Troubleshooting section to README.md or create docs/troubleshooting.md covering the top 3 to 5 recurring issues from your issue tracker. Each entry should name the symptom, cause, and fix. Example:

### "Module not found" after installation
**Symptom:** `Cannot find module 'your-package'` on import.
**Cause:** Stale `node_modules` or wrong install directory.
**Fix:**
\`\`\`bash
rm -rf node_modules package-lock.json && npm install
\`\`\`

Detection

  • ID: developer-documentation.content-quality.troubleshooting

  • Severity: low

  • What to look for: Check for a troubleshooting section, FAQ, or "Common Issues" page in the README or docs. This should address the problems that users are most likely to hit during setup or first use. Check GitHub issues for recurring questions -- if the same question is asked 3+ times, it should be in the docs. Count all instances found and enumerate each.

  • Pass criteria: A troubleshooting or FAQ section exists that addresses at least 3 common issues. Issues include the symptom (what the user sees), the cause, and the fix.

  • Fail criteria: No troubleshooting section exists, or it exists but covers fewer than 3 issues, or issues are listed without resolution steps.

  • Skip (N/A) when: The project is brand new with no users yet (fewer than 10 GitHub stars AND fewer than 100 npm downloads AND no open issues).

  • Detail on fail: Example: "No troubleshooting or FAQ section in README or docs" or "GitHub issues show 5 users asking about the same CORS error but docs don't mention it"

  • Remediation: Start with the top 3-5 issues from your GitHub issues or support channels:

    ## Troubleshooting
    
    ### "Module not found" error after installation
    
    **Symptom:** `Cannot find module 'your-package'` when importing
    
    **Cause:** Package was installed in the wrong directory or node_modules is corrupted.
    
    **Fix:**
    ```bash
    rm -rf node_modules package-lock.json
    npm install
    

Taxons

History