In a music-streaming app's design system, teams say the docs are always out of date; how would you detect stale pages and make someone own fixing them?
answer
- wrong, missing or unfindable
- code changed after the page
- zero-result searches
- page feedback and support threads
- a named owner per page
basics
~20 sSplit the complaint into wrong, missing and unfindable pages, and detect each: code changed after its page, failing examples, zero-result searches, negative feedback, support threads correcting the docs. Give every page a named owner and route fixes to them.
solid answer
~50 s'Always out of date' usually hides three problems — **wrong** pages, **missing** pages and **unfindable** pages — so I'd collect signals for each. For wrong: pages whose component **changed after the page was last edited**, and examples the docs build no longer renders. For missing or unfindable: **zero-result search queries** and top searches followed by support questions. Plus direct **page feedback** and support threads where the answer contradicts the docs. Edit age alone is a weak signal, since stable components keep old pages. Then ownership: every page gets a **named owner** — normally the team that owns the component — recorded on the page and in an owners file that routes doc changes to them, with docs in the definition of done. A weekly stale-candidate report turns signals into backlog items for those owners. A single writer owning everything, or an annual docs sprint, does not keep up.
go deeper
Recall the main staleness signals — code changed after the page, failing examples, zero-result searches, page feedback — and that each page has a named owner.
Explain why edit age is a weak signal, and how wrong, missing and unfindable pages each show up in different data.
Demonstrate a working loop: a regular stale-candidate report, triage, routing to named owners, fixes at the cause, and trend checks proving it improved.
Treat persistent staleness as a capacity and incentive problem across teams, and decide which docs the system team funds centrally versus devolves to owners.
## The complaint is a symptom In a **design system**, 'the docs are always out of date' is rarely one problem. Unpacked, it is usually three: - **Wrong** — the page describes an older API or behaviour than the component has. - **Missing** — the thing the reader needs has no page at all. - **Unfindable** — the page exists and is correct, but readers search with words it does not use. Each has different signals and a different fix, so the first step is measurement rather than a rewrite. ## Signals that a page is stale | Signal | What it suggests | Where it comes from | |---|---|---| | Component code changed after its page | The page may describe an old API | Compare the last change to the component with the last change to its page | | Failing or skipped examples | Examples no longer match the component | The docs build results | | Zero-result searches | A missing page or a missing synonym | Site search logs | | Top searches followed by support questions | The page exists but does not answer | Search logs plus the support channel | | Negative page feedback | Readers found it wrong or unclear | A 'was this helpful?' control with a free-text box | | Support answers that correct the docs | Known-wrong content | Tagging support threads where the answer contradicts a page | Design the feedback control so its answers are usable: ask one question ('did this page answer your question?'), invite a short free-text reason on a 'no', and attach the page and version automatically. A thumbs-down with no context tells an owner that something is wrong but not what. **Edit age alone is a weak signal.** A button that has not changed in a year legitimately has a page that has not changed in a year. Staleness is the gap between what the component does and what the page says, not the calendar. On a music-streaming app, a typical finding: the **queue list** component gained drag-to-reorder two releases ago, its page never mentions it, searches for 'reorder' return nothing, and three teams asked in the support channel how to enable it. ## Turning signals into work 1. **Build a stale-candidate report** on a regular cadence: pages whose component changed since the page did, pages with negative feedback, and the top zero-result queries. 2. **Triage** each candidate as wrong, missing or unfindable. 3. **Route** it to the page's owner as a backlog item, not a message in a chat that scrolls away. 4. **Fix the cause** where possible: a missing synonym becomes a search keyword; a repeated support answer becomes a page section. ## Ownership - **Every page has a named owner**, normally the team that owns the component, recorded in the page's metadata and in an owners file that routes doc changes to them for review. - **Pages without a component** — foundations, patterns, principles — get an explicit owner too; these are the pages most often orphaned. - **Platform sections** for web and native mobile are owned by the maintainers of that platform's implementation. - **Docs are in the definition of done**: a component change is not finished until its page reflects it, which prevents most new staleness at the source. - **Show 'last reviewed' and the owner on the page** — it tells readers how much to trust it and tells owners the page is theirs. ## What does not work - **One technical writer owning every page.** Writers improve clarity enormously, but they cannot know every component change as it happens. - **An annual docs sprint.** It fixes a snapshot; staleness returns the week after. - **Treating low traffic as permission to neglect.** A rarely visited page may simply be unfindable, which is itself a finding. ## Checking that it worked Track the same signals over time: fewer zero-result searches, fewer support threads that correct the docs, a shorter gap between component changes and page changes, and page feedback trending positive. If the report keeps listing the same owners' pages, the problem is capacity or incentives in those teams, and that is a conversation for the system's leads, not a docs fix.
- A frequent search query returns zero results, but the page exists under another name; what do you change?Add the reader's term as a search keyword or synonym on the page, and consider whether the page title or the component name itself is the problem. If many readers call the component by a different name, that name may belong in the page's opening line. Then watch whether the query starts returning clicks instead of support questions.
- The same team's pages keep appearing on the stale report; how do you respond?Treat it as a capacity or incentive signal rather than a documentation fault. Talk to that team's lead about whether docs are really in their definition of done and whether they have time for it. Options include pairing them with a writer, moving shared guidance to the system team, or accepting a slower cadence explicitly.
saying these in an interview costs you the question
- A page not edited in the last year must be stale.
- Zero-result searches are typo noise and can be ignored.
- Hiring one technical writer to own every page solves staleness.
- An annual documentation sprint keeps the docs current.
- Docs ownership can sit with 'the system team' in general, without names.