> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Keep Documentation Current with Product Changes

> Identify outdated docs and update them based on new customer questions and product changes

You shipped a new feature. You updated the UI. You changed how something works. But did you update the docs?

**Your help center is now lying to customers.** They follow the steps, it doesn't work, they open a ticket frustrated.

**This guide shows you how to identify which docs are outdated and update them systematically.**

## The Outdated Docs Problem

**What happens after product changes:**

* 🚢 Team ships feature updates
* 📚 Docs team (if you have one) doesn't know
* ❓ Customers follow old docs, get confused
* 😤 Support tickets: "This doesn't work!" (it does, docs are wrong)
* 🔥 More tickets from outdated docs than from no docs

**The truth**: Outdated documentation is worse than no documentation. It wastes customer time AND support time.

## What You'll Achieve

With BuildBetter:

* ✅ **Identify outdated docs** from customer questions
* ✅ **Prioritize updates** by customer impact
* ✅ **Find UI changes** customers are confused by
* ✅ **Keep docs in sync** with product changes
* ✅ **Prevent documentation debt**

<Info>
  **Time investment**: 30 mins/week to review + 1-2 hours/month for updates. **Impact**: Prevent 10-20 "docs are wrong" tickets/month.
</Info>

## Prerequisites

<Check>
  BuildBetter account with support tickets or customer calls
</Check>

<Check>
  Existing help documentation
</Check>

<Check>
  Product change log or release notes
</Check>

***

## Step 1: Find Documentation Gaps

\[screenshot: Support tickets mentioning "doesn't work" or "can't find"]

<Steps>
  <Step title="Import Recent Support Tickets">
    Focus on tickets AFTER your last product release:

    1. Import last 30 days of tickets
    2. Filter for common phrases:
       * "Doesn't work"
       * "Can't find"
       * "Instructions wrong"
       * "Not where it says"

    \[screenshot: Filtered signals showing documentation complaints]
  </Step>

  <Step title="Ask Chat to Find Documentation Issues">
    **Query**: "Which help articles or documentation are customers saying is incorrect or outdated? What are they confused about?"

    \[screenshot: Chat identifying outdated doc patterns]

    **Example output**:

    ```
    Outdated Documentation Identified (Last 30 Days):

    1. "How to Export Data" Article (14 tickets)
       Customer complaints:
       - "Export button not in top right anymore"
       - "Don't see CSV option mentioned in article"
       - "Steps don't match what I see"

       Root cause: UI changed in v2.3, docs not updated

    2. "Adding Team Members" Article (9 tickets)
       Customer complaints:
       - "Settings menu looks different"
       - "Can't find 'Invite' button where article says"

       Root cause: Settings redesigned last month

    3. "API Authentication" Article (7 tickets)
       Customer complaints:
       - "API key generation different now"
       - "Screenshot shows old UI"

       Root cause: API dashboard updated
    ```
  </Step>
</Steps>

***

## Step 2: Cross-Reference Product Changes

\[screenshot: Product changelog with dates]

<Steps>
  <Step title="Review Recent Product Changes">
    Check your changelog/release notes:

    * Which features changed?
    * What UI updates shipped?
    * Which workflows are different?

    **Map to help docs**:

    * Feature changed → Which articles mention it?
    * UI updated → Which screenshots are outdated?
    * Workflow different → Which step-by-step guides need updates?
  </Step>

  <Step title="Identify High-Impact Updates">
    **Query**: "Based on customer tickets, which product changes are causing the most confusion? Prioritize by ticket volume."

    Focus on updating docs for changes that:

    * Generated most tickets
    * Affect most common workflows
    * Impact new users (onboarding docs)
  </Step>
</Steps>

***

## Step 3: Update Documentation Systematically

\[screenshot: Side-by-side comparison - old doc vs updated doc]

<Steps>
  <Step title="Create Update Queue">
    **Query**: "Generate a prioritized list of documentation updates needed, with: article name, what changed, urgency (high/medium/low), and estimated effort."

    **Example output**:

    ```
    Documentation Update Queue:

    🔴 HIGH PRIORITY
    1. "How to Export Data"
       - What changed: Button moved from top right to Reports menu
       - Urgency: HIGH (14 tickets in 30 days)
       - Effort: Low (update 2 screenshots, change 1 sentence)
       - Impact: Prevents ~5 tickets/week

    2. "Adding Team Members"
       - What changed: Settings menu redesigned
       - Urgency: HIGH (9 tickets)
       - Effort: Medium (update 3 screenshots, rewrite steps)
       - Impact: Prevents ~3 tickets/week

    🟡 MEDIUM PRIORITY
    3. "API Authentication"
       - What changed: New API dashboard
       - Urgency: MEDIUM (7 tickets, but power users)
       - Effort: High (complete rewrite needed)
       - Impact: Prevents ~2 tickets/week
    ```
  </Step>

  <Step title="Update Articles">
    For each article:

    **Before you start**:

    1. Open the app/feature yourself
    2. Go through the current steps
    3. Take new screenshots
    4. Note what's different

    **Update process**:

    1. Update screenshots (highlight new UI elements)
    2. Revise step-by-step instructions
    3. Test: Can someone follow these new steps?
    4. Add "Last updated: \[Date]" to article
    5. Publish

    **Pro tip**: Use Chat to help rewrite

    * **Query**: "Rewrite this help article based on the new UI. Old steps: \[paste old]. New UI: \[describe changes]."
  </Step>

  <Step title="Add Change Indicators">
    In help center:

    * Tag recently updated articles: "✅ Updated for v2.3"
    * Show last updated date prominently
    * Add changelog at bottom: "What changed in this article"

    \[screenshot: Help article with "Updated Mar 2024" badge]

    Helps customers know docs are current.
  </Step>
</Steps>

***

## Step 4: Prevent Future Documentation Debt

\[screenshot: Documentation workflow integrated into release process]

<Steps>
  <Step title="Create Documentation Review Workflow">
    **Before each release**:

    1. Product team shares changelog
    2. Review which help docs are affected
    3. Update docs BEFORE feature ships
    4. Mark as "Updated for vX.X"

    **After each release**:

    1. Week 1: Monitor support tickets for confusion
    2. Week 2: Update docs based on real customer questions
    3. Week 4: Ask Chat: "Any new documentation gaps this month?"
  </Step>

  <Step title="Set Up Monthly Documentation Audit">
    **First Monday of each month** (30 mins):

    **Query Chat**:

    * "Which help articles got the most 'this didn't work' tickets last month?"
    * "Are there new customer questions we don't have docs for?"
    * "Which articles might be outdated based on product changes?"

    \[screenshot: Monthly documentation health report]

    Update 2-3 articles per month minimum.
  </Step>

  <Step title="Track Documentation Health">
    **Metrics to monitor**:

    * Tickets mentioning "docs wrong" or "doesn't match"
    * Help article deflection rate (views vs tickets)
    * "Not helpful" feedback on articles
    * Articles with >6 months since update

    \[screenshot: Documentation health dashboard]

    **Good signal**: Deflection rate stable or improving
    **Bad signal**: Deflection rate declining (docs getting outdated)
  </Step>
</Steps>

***

## Real Example: Jamie's Documentation Maintenance

**Background**: Jamie is Head of Support. Good help docs. But product ships weekly. Docs always outdated.

**The Problem**:

* Product team ships, doesn't tell support
* Support finds out when customers complain
* Docs perpetually 2-3 weeks behind
* "Docs are wrong" became most common ticket

**The Solution (with BuildBetter)**:

**Week 1**: Set up monitoring

* Import all support tickets
* Filter for documentation complaints
* Found 23 tickets in last month about wrong docs

**Week 2**: Audit existing docs

* Cross-referenced with recent product changes
* Found 8 articles outdated
* Prioritized by ticket volume
* Updated top 5 (3 hours total)

**Week 3**: Created weekly workflow

* **Monday**: Product team shares changelog
* **Tuesday**: Jamie reviews which docs affected
* **Wednesday**: Updates docs before feature ships
* **Friday**: Check for any surprise confusion

**Month 1**: Automated monitoring

* Monthly Chat query: "Documentation gaps?"
* Review outdated article list
* Update 2-3 per month

**Results after 90 days**:

* "Docs are wrong" tickets: 23/month → 4/month (-83%)
* Documentation deflection rate: 45% → 68%
* Customer satisfaction with docs: 3.2/5 → 4.4/5
* Time spent updating: 1 hour/week (sustainable)

**Jamie's quote**: "We went from reactive (fix docs after customers complain) to proactive (update docs before feature ships). BuildBetter tells us which docs need attention before they become a support burden."

***

## Best Practices

<Check>
  **Update BEFORE shipping**: Include doc updates in your definition of "done" for features
</Check>

<Check>
  **Date your articles**: Show "Last updated: March 2024" so customers know freshness
</Check>

<Check>
  **Small updates weekly > Big updates quarterly**: Easier to maintain currency
</Check>

<Check>
  **Screenshot liberally**: Outdated screenshots = most common complaint
</Check>

<Check>
  **Test your own docs**: Follow the steps yourself before publishing updates
</Check>

<Check>
  **Archive old versions**: Don't delete, mark as archived for older product versions
</Check>

***

## Common Questions

<AccordionGroup>
  <Accordion title="How do I know which docs to update first?">
    **Prioritize by**:

    1. Customer complaints (ticket volume)
    2. Common workflows (affects most users)
    3. New user docs (onboarding critical)
    4. Recent product changes (most likely outdated)

    Use BuildBetter to surface #1 automatically.
  </Accordion>

  <Accordion title="Should we update every doc when UI changes slightly?">
    **Depends on impact**:

    ✅ Update if:

    * Buttons moved or renamed
    * Steps don't work anymore
    * Screenshots clearly wrong
    * Causing tickets

    ⏸️ Don't update if:

    * Minor color/style changes
    * Functionally identical
    * Not causing confusion

    Let customer tickets guide you.
  </Accordion>

  <Accordion title="How do we keep docs updated when we ship daily?">
    **Triage approach**:

    * **Breaking changes**: Update docs same day
    * **New features**: Update within 3 days
    * **Minor tweaks**: Batch update weekly
    * **Bug fixes**: Usually don't need doc updates

    Monitor tickets to see if something needs immediate attention.
  </Accordion>

  <Accordion title="What if product team doesn't tell us about changes?">
    **Build it into process**:

    1. Add "Documentation updated?" to PR checklist
    2. Automatic Slack post: "Feature X shipped. Docs need review?"
    3. Use BuildBetter as safety net (finds gaps from tickets)

    **Or**: Weekly sync with product team on upcoming changes
  </Accordion>
</AccordionGroup>

***

## Documentation Maintenance Checklist

### Weekly (30 mins)

<Check>Review product changelog for doc-affecting changes</Check>
<Check>Update docs for shipped features (before release if possible)</Check>
<Check>Check for "docs wrong" tickets this week</Check>

### Monthly (1-2 hours)

<Check>Ask Chat: "Documentation gaps from last month?"</Check>
<Check>Update 2-3 most outdated articles</Check>
<Check>Review help article metrics (views, deflection)</Check>
<Check>Update screenshots for UI changes</Check>

### Quarterly (Half day)

<Check>Full documentation audit</Check>
<Check>Archive docs for sunset features</Check>
<Check>Reorganize/restructure if needed</Check>
<Check>Review documentation health metrics</Check>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Write New Documentation" href="/pages/Use%20Cases/cs/writing-documentation">
    Create help docs from customer questions
  </Card>

  <Card title="Reduce Support Tickets" href="/pages/Use%20Cases/cs/ticket-analysis">
    Full ticket deflection strategy
  </Card>

  <Card title="Document Generation" href="/pages/Documents/document-generation">
    Auto-generate docs from patterns
  </Card>

  <Card title="Knowledge Management" href="/pages/Organization/collections-overview">
    Organize all your documentation
  </Card>
</CardGroup>

***

**Good documentation isn't written once—it's maintained continuously.**

<Info>
  The best support teams treat documentation like code: version it, review it, update it with every release. Outdated docs create more problems than they solve.
</Info>

<Note>
  Based on analysis of 200+ support teams. Teams that update docs within 1 week of product changes see 40% fewer "docs are wrong" tickets than teams that batch update monthly.
</Note>