If They Cannot Find It, You Did Not Write It: Search and Findability
Most documentation fails at retrieval, not writing. How to title docs as search queries, build linking habits, kill duplicate pages, and measure findability.
An engineer spends forty minutes writing a clear guide to the deployment process. Four months later, a teammate needs exactly that information, searches for it, does not find it, asks in chat, gets a partial answer from memory, and — here is the expensive part — writes a new, slightly worse guide. Now there are two documents, they disagree, and the next searcher's odds got worse, not better.
This is the standard failure mode of team knowledge, and it is not a writing problem. The information existed. It was accurate. It was even well-written. It failed at retrieval — and knowledge that cannot be retrieved has the same value as knowledge that was never captured, minus the forty minutes.
This post is about the retrieval half of documentation: how people actually search, how to title and write documents so search finds them, how linking multiplies findability, how to stop the duplicate spiral, and how to measure whether any of it is working.
How people actually look for things
Findability engineering starts with an honest model of the searcher, and the honest model is unflattering. Decades of research on information-seeking behavior converge on a few consistent patterns:
Queries are short. People search internal tools the way they search the web: two or three words, no boolean operators, no category filters. "expense policy." "deploy staging." "laptop refresh." If your document is only findable via a longer or more precise query, it is not findable.
People satisfice. Searchers do not evaluate all results and pick the best; they scan the first few, click the first plausible one, and stop. If the right document is result #4 with a vague title, the wrong document at #1 wins.
Attempts are few and short. Studies of search behavior consistently find that users try once, maybe twice, reformulating slightly, and then bail to another channel. For internal knowledge, "another channel" means interrupting a human. Every failed search has a second cost: it trains the searcher that search does not work, so next time they skip it entirely and go straight to chat.
People forage by scent. When browsing rather than searching, readers follow "information scent" — clicking whatever link text smells most like their goal. Vague link text ("click here," "more info," "Q3 doc") kills the scent trail.
People ask in their own vocabulary. The searcher types "time off," the document says "leave of absence policy." The searcher types "on-call," the document says "incident rotation." Vocabulary mismatch is the single most common cause of failed internal search, because internal search engines are mostly literal — they match words, not meanings.
Every technique below is a response to one of these behaviors. None of them require better software; they require writing and curating for the searcher who actually exists — hurried, literal, and one failed query away from interrupting a colleague.
Titles are queries: the highest-return fix in knowledge management
If you change one thing after reading this post, change how documents are titled. The title is what search matches most heavily, what result lists display, and what the satisficing scanner judges in half a second. A title works when it contains the words a seeker would type, in the order they would scan them.
The test for every title: complete the sentence "someone will find this when they search for ___." If you cannot fill the blank with the title's own words, retitle.
Real-world before and after:
| Before (author's label) | After (seeker's query) |
|---|---|
| Q3 Infra Notes | How to deploy to staging and production |
| PTO Process v2 FINAL | How to request time off |
| Misc onboarding stuff | New hire first-week checklist |
| Brand | Logo files and brand colors |
| Postmortem 2025-08-14 | Post-mortem: checkout outage, Aug 14 2025 |
| The Jenkins Situation | CI pipeline: common failures and fixes |
| Team norms | How we run meetings and make decisions |
The pattern in every row: the "after" title states the task or question, front-loads the distinguishing words, uses no insider nicknames, and would make sense to someone hired yesterday. Note that dates and titles coexist fine — "Post-mortem: checkout outage, Aug 14 2025" is both browsable in a list and matchable by "checkout outage."
Three title rules worth enforcing:
- Name the task or question, not the artifact. Readers search for what they are trying to do, not for the genre of document you produced. "Reset a customer's 2FA" beats "Support procedures addendum."
- Front-load. Lists truncate. Put the differentiating words first: "Expenses: international travel" not "A guide to the international travel portion of the expense process."
- No status, no versions, no "final." Version words in titles are noise to search and a lie within a month. Status lives in metadata; the title stays stable so links stay stable.
Retitling is also the cheapest findability project that exists. Pull your 25 most important documents, apply the test, and retitle the failures. It takes an hour, requires no migration, and improves every future search against those documents.
Write for the index: first paragraphs, synonyms, and the vocabulary problem
Search engines weigh titles most, but they index bodies — and scanning readers judge the first paragraph. Both facts have writing consequences.
Open with the answer's context, not throat-clearing. The first paragraph should restate the document's purpose in plain words: "This page explains how to request time off, how far in advance to ask, and who approves it." That sentence is simultaneously a scanner's confirmation ("right doc") and a keyword-rich target for the index. Documents that open with history ("In 2023 we revisited our approach to leave...") lose both audiences.
Include the synonyms, deliberately. The vocabulary mismatch problem — "time off" vs "PTO" vs "leave" — has a low-tech fix: make sure the words people actually use appear somewhere in the document, even if your official term differs. One natural sentence handles it: "This PTO policy (also called leave or time off) covers..." For heavily search-missed terms, some teams keep an explicit "also known as" line under the title. It looks slightly redundant to the author and works perfectly for the index.
Keep a glossary, and link it. Every team develops private vocabulary — project code names, acronyms, the internal name for the customer database. A single glossary page mapping internal terms to plain language pays off twice: humans read it, and its presence means at least one indexed page connects "Odyssey" to "the billing migration project."
Headings are secondary titles. Search results often deep-link to sections, and scanners navigate by headings. Apply the title-as-query rule to ## headings too: "Rotating API keys" beats "Additional considerations."
Links: the findability infrastructure nobody budgets for
Search is one door into a document. Links are all the other doors, and they have a property search lacks: they deliver the document at the moment of need, without the reader having to formulate a query at all. A knowledge base with excellent search and no linking discipline still fails, because the best retrieval is the one the reader never had to perform.
Four linking habits with outsized returns:
Link from where the work happens. The expense policy linked inside the expense tool. The runbook linked from the alert. The style guide linked in the pull request template. The onboarding doc linked in the offer-acceptance email. Each of these turns a potential search (with its failure odds) into a guaranteed delivery. Audit method: collect a week's worth of "where is the doc for X?" questions from chat; each one identifies a workflow missing a link.
Answer with links, permanently. When someone asks a question in chat and a document answers it, reply with the link — even if typing the answer would be faster. This does three jobs: the asker gets the answer, the asker learns the document exists (updating their model of what search can find), and the thread itself becomes a searchable trail pointing to the document. Teams with this habit compound findability daily; teams that answer from memory re-answer the same question monthly. If the document doesn't exist, that is a capture moment — the mechanics of turning recurring questions into permanent answers are covered in our guide to running an internal Q&A knowledge base.
Every document links onward. A "Related" section with two to four links at the bottom of each page turns dead ends into trails. The reader who found the deployment guide probably wants the rollback runbook and the environments reference next; hand them over. Follow the information-scent rule for link text: the link says what the destination is ("Rollback runbook for failed deploys"), never "see here."
Hubs concentrate scent. A curated hub page per topic — the ten best links with a line of context each — gives browsers a high-scent starting point and gives search a keyword-dense page that matches broad queries ("onboarding," "security") which no single specific document matches well. Hub construction and placement are part of structural design, covered in depth in structuring a knowledge base people can actually navigate.
Duplicates: the findability killer that looks like productivity
Every duplicate document is an attack on findability. It splits search relevance across copies, guarantees the copies drift into disagreement, and — worst — teaches readers that finding a document is not the same as finding the document, so they stop trusting retrieval altogether. Three search results for "expense policy," two of them outdated, is functionally worse than zero results: zero results triggers a question in chat; three results triggers a confident wrong answer.
Duplicates are not caused by carelessness. They are caused by rational economics: when finding the existing document costs more than writing a new one, people write. Which means the fix is not a policy memo ("please don't duplicate") but changing the economics:
Make search-before-write a norm with teeth. The habit to install: before creating any document, search for two minutes; if something related exists, extend or update it instead of starting fresh. Cheap to say, and it sticks best when leads model it visibly — "I was going to write this up, found Priya's doc from March, updated it instead" is a culture-setting sentence.
Declare canonical pages. For every high-traffic topic (expenses, deploys, PTO, brand assets), one page is the page, marked as such — a "Canonical" label, a note in the header, whatever your tool supports. Other pages on the topic link to it rather than restating it. When someone finds two pages disagreeing, the canonical marker resolves the conflict without a meeting.
Merge with stubs, not deletions. The duplicate cleanup ritual: quarterly, take the topics with multiple pages, merge content into the canonical page, and replace each duplicate with a one-line stub — "This page has moved: [canonical link]." Stubs preserve every existing bookmark and inbound link while funneling all readers to one place. Deleting without a stub breaks links and re-teaches distrust.
Watch the copy-paste smell. When you find yourself pasting three paragraphs from one document into another, stop and link instead. Every pasted copy is a future contradiction with a start date.
Illustrative math on why this matters: suppose your team answers a routine question correctly 95% of the time from a single maintained document. Split that content across three drifting copies and let two go stale, and the searcher who satisfices on the first plausible result is now getting a correct answer closer to a coin flip — while being more confident, because they found "the documentation."
Close the loop: mine your failed searches
Everything above is preventive. The corrective mechanism is noticing retrieval failures and patching them, one per failure. Failed retrievals announce themselves in two places:
Search analytics, if you have them. Two reports matter: top queries with zero results (vocabulary or coverage gaps — create the page or add the synonym), and top queries where users don't click anything (title problems — the right page probably exists with the wrong name). Fifteen minutes a month on these two lists, each miss producing one action: write, retitle, or link.
Chat, if you don't. Every "does anyone know," "where is the," and "how do I" in your team channels is a search that failed or was never attempted. Once a month, sweep a week's sample and sort into three buckets: doc exists, wasn't found (fix the title or add the workflow link), doc exists, wasn't trusted (fix staleness — see below), doc doesn't exist (write it, titled as the question that was just asked, which is conveniently the perfect title).
That last move deserves emphasis: the question someone just asked is a pre-validated title. When you write a document in response to a real question, title it in the asker's words, not your official terminology. They have just told you the query; use it.
Staleness belongs in this loop too, because findability includes trust. A found document that readers do not believe ("is this still true?") produces the same chat interruption as a missing one. Visible last-reviewed dates and a habit of archiving dead pages keep search results believable — and keep the wrong answers from outranking the right ones.
A chat sweep, worked
Here is what one week of a real (lightly disguised) team channel yields, and what each item becomes:
Mon: "anyone remember how to get access to the analytics db?" — Doc existed, titled "Data platform notes." Retitled to "Get read access to the analytics database"; link added to the data team's hub.
Tue: "what's our policy on speaking at conferences?" — No doc. Fifteen-minute page written, titled exactly "Can I speak at a conference? Policy and approval," in the asker's words.
Wed: "is the onboarding checklist the one in Docs or the one in the drive folder?" — Duplicate detected. Merged into the Docs version, stub left in the folder, canonical label added.
Thu: "how do I rotate the staging certs? the wiki page says 2024 on it" — Doc existed and was correct, but the stale date killed trust. Steps verified, last-reviewed date bumped, and the alert that fires on cert expiry now links the page directly.
Fri: "who owns the pricing page?" — Not a document problem at all; an ownership question. Answered from the directory, plus one line added to the pricing hub: "Owner: growth team."
Five interruptions, five distinct root causes — a bad title, a missing page, a duplicate, a trust failure, and an ownership gap — and five permanent fixes, totaling maybe ninety minutes of work. That is the texture of findability improvement: not a project, just a habit of treating every "where is..." as a bug report with the reproduction steps included.
Questions are the most findable format
One structural observation ties this together: the closer a document's form is to the seeker's question, the more findable it is. This is why FAQ pages punch above their weight, and it is the core argument for running part of your knowledge base in question-and-answer format rather than prose documents.
A Q&A system makes findability properties automatic that prose documentation achieves only through discipline: the title is a question in a real asker's vocabulary; one question has one canonical thread rather than scattered partial answers; an accepted answer marks what is current and trusted; and duplicate questions get linked to the original by the community, performing the merge ritual continuously instead of quarterly.
This is why Openbook includes a Q&A room — a private Stack Overflow with markdown questions, tags, voting, and accepted answers — alongside Docs and Wiki rooms, with global ⌘K search spanning all of them. Prose documentation holds the reference material; Q&A catches the long tail of specific, situational questions that no one would think to write a page about; and one search covers both, so the seeker doesn't need to know which format holds their answer. Whatever tools you use, the principle stands: give questions a first-class home, and search improves without anyone writing better prose. See how the rooms fit together on our features page.
Measuring findability: the find-it test
Findability feels subjective until you measure it, and the measurement is cheap. Two instruments:
The find-it drill (quarterly, 20 minutes). Pick five pieces of information that matter — not documents, information: "what's our SSO provider?", "how do I expense a conference?", "who approves contract redlines?" Ask someone who did not write the docs (ideally a recent hire) to find each answer, timed, while you watch silently. Score each: found in under a minute; found in one to three minutes; found only via a path they'd never repeat; not found. Every result worse than "under a minute" identifies a specific fix — and watching someone search your knowledge base is reliably humbling in the most useful way.
Three tracked numbers (monthly).
- Zero-result and zero-click rates from search analytics, if available.
- Chat deflection count: "where is / does anyone know" questions in a sample week. The single best proxy for findability, trending down if your fixes are landing.
- Duplicate count on canonical topics: number of high-traffic topics with more than one live page. Target: zero, enforced by the merge ritual.
Resist measuring page views as a findability metric; a stale page can be heavily viewed precisely because it ranks well and misleads everyone.
Next steps
Findability improves through small, compounding fixes — no migration, no committee:
- Today (1 hour): Retitle your 25 most important documents using the "someone will find this when they search for ___" test.
- This week: Start the answer-with-links habit personally. Every question you answer in chat gets a link — to an existing doc, or to the doc you just created and titled with the asker's own words.
- This month: Run the duplicate merge on your five highest-traffic topics; leave stubs. Add "Related" links to your twenty most-visited pages. Do one chat sweep and patch every miss.
- Quarterly: Run the find-it drill with a recent hire, and track your three numbers.
The forty-minute deployment guide from the opening only becomes an asset the day someone finds it in thirty seconds. Write for the searcher, link from the workflow, keep one page per topic — and the knowledge your team already captured starts paying rent.
Openbook puts docs, wiki, and Q&A behind one global search, so the answer is findable no matter which format holds it. Start free at openbook.work.