A design system's docs site has 150 pages, yet a museum kiosk team keeps asking in chat where idle-timeout guidance lives and which component to use. How do you fix the structure?
answer
- the content exists, the path does not
- collect the real questions
- readers' words versus page names
- a tree test before a redesign
- task pages and cross-links
basics
~20 sTreat it as an information-architecture problem: learn where readers expect answers from their chat questions, their wording and a tree test. Then organise around tasks - named pattern pages, readers' synonyms, cross-links from components to patterns, and audience entry points.
solid answer
~40 sRepeated 'where is it?' questions usually mean the content exists but the **path to it does not**. I would start by collecting the questions asked in chat and comparing their words with our page names: the kiosk team says 'timeout' while the guidance may sit on a page called 'session expiry', inside a dialog component page. Then I would run a quick **tree test** - give readers tasks and a text-only version of the navigation, and see where they look. Typical fixes: move task guidance into a **patterns** section with task-named pages, add the readers' **synonyms** to titles and summaries, **cross-link** each component page to the patterns it appears in, and give designers and engineers clear entry points. Re-run the tree test afterwards and watch whether the repeat questions stop.
go deeper
Recall that repeated 'where is it' questions usually mean the content exists but its grouping or naming does not match what readers expect.
Explain the causes - buried task guidance, vocabulary mismatch, missing pattern pages, orphans - and how cross-links and entry points fix them.
Lead the diagnosis with evidence: mine support questions, run a tree test, change the worst paths, and measure task success before and after.
Weigh investment in documentation structure against support load and adoption, and decide who owns the site's architecture as the system grows.
## The symptom A design system's documentation site has grown to 150 pages. A team building a museum ticketing kiosk keeps asking in the system's support chat two kinds of question: where the guidance on **idle timeout** is (what the kiosk does when a visitor walks away mid-purchase), and **which component** to use for the warning. The guidance exists. Readers cannot find it. That is an **information architecture** (IA) problem: how content is grouped, named and linked. Adding more pages does not fix it; it usually makes it worse. ## Diagnose before restructuring 1. **Collect the real questions.** Pull the last few months of support-chat questions that begin 'where is' or 'which component'. They are direct evidence of what readers look for and in what words. 2. **Compare readers' words with page names.** If readers say 'timeout', 'walk-away' or 'inactivity' and the page is titled 'session expiry', the name is the barrier. 3. **Find where the guidance actually lives.** Often task guidance has been written into one component's page, such as the dialog page, where only readers who already know the answer would look. 4. **Run a tree test.** A tree test gives participants a text-only version of the navigation and a set of tasks ('Where would you find what to do when a visitor stops interacting?') and records where they click. It isolates structure and naming from visual design, and a handful of participants from consuming teams is often enough to reveal the worst problems. ## Common causes and fixes | Cause | Symptom | Fix | |---|---|---| | Task guidance buried in a component page | readers searching by task find nothing | move it to a pattern page named for the task; link from each component involved | | Page names in the system team's vocabulary | readers' words do not match titles | use readers' terms in titles and summaries; list synonyms | | No patterns section, or a thin one | 'which component do I use for this?' questions | build out task-level pattern pages | | Navigation mirroring internal teams | readers cannot guess where a topic sits | restructure around foundations, components, patterns and task entry points | | Orphan pages | pages reachable only by a direct link | add every page to navigation and to related-content links | ## Making the fix stick - **Cross-link both ways.** The idle-timeout pattern links to each component it uses - the dialog, the countdown, the button - and each of those component pages links back under a related-patterns heading. Readers who arrive from either direction reach the answer. - **Entry points by audience.** A 'for designers' and a 'for engineers' starting page, each routing to the most asked-for foundations, components and patterns. - **Answer in chat with a link.** When a question is asked again, answer it with a link to the page; if there is no page to link to, that is a gap to fill. Over time the chat becomes a feed of missing or badly placed content. Search helps readers who know the right words, but it does not fix a structure whose names and groupings do not match how readers think; readers who browse still get lost. So structure is fixed first, and search is tuned alongside it. ## Measuring the result Re-run the same tree test tasks after the change and compare **task success** - the share of participants who found the right page - and how directly they got there. Then watch the support chat: the same 'where is' questions should become rare. Neither measure needs a large study; both need the same tasks before and after so the comparison is fair. ## What not to do - **Redesign the whole site at once** based on opinion; test the structure first and change the worst paths. - **Add another index page** listing everything; a longer list is not a clearer structure. - **Blame readers for not searching**; repeated questions are data about the site. - **Rename pages with no redirects**, breaking links in existing answers and bookmarks. - **Restructure without telling consumers**; announce the new navigation and point to where familiar pages moved, so the change does not generate a new wave of 'where is it' questions.
- What does a tree test measure that a normal usability review of the documentation site does not?A tree test isolates structure and naming. Participants see only a text version of the navigation, with no visual design, search or page content, and try to find where a task's answer lives. That shows whether the grouping and labels match readers' expectations, independent of how the pages look.
- How do you decide whether idle-timeout guidance is a pattern or part of the dialog component's page?Ask whether the guidance is about using one component or about completing a task that spans several. Idle timeout involves a warning, a countdown, an action to continue and a reset, so it is a pattern. The dialog page covers the dialog itself and links to the pattern as one place it is used.
saying these in an interview costs you the question
- Repeated 'where is it' questions mean readers are not reading the docs carefully.
- Adding a better search box alone fixes a structure problem.
- Writing more pages is the way to answer more questions.
- Page names should use the system team's precise internal terms, whatever readers say.
- Restructuring the site needs no evidence beyond the system team's opinion.