Documentation Nobody Can Find Is Documentation That Does Not Exist
Key takeaway: The bottleneck in internal documentation is almost never writing it — it is discovery. A correct, well-written answer that nobody can find has the practical value of no answer at all.
The Gap Between Written and Findable
An organisation with years of accumulated engineering practice usually has the answer to most common questions written down somewhere, in a wiki page, a README, a Slack thread someone bookmarked. The problem is rarely that the answer does not exist — it is that finding it requires knowing it exists, knowing roughly where to look, and getting lucky with search terms that happen to match how it was originally phrased.
The practical consequence is that people ask a colleague instead of searching, which is faster in the moment and means the same question gets answered individually, repeatedly, forever, imposing a small ongoing tax on whoever happens to know the answer.
Why Wiki Search Specifically Fails
Most general-purpose wiki platforms implement basic keyword search without the ranking sophistication of a modern search engine, and internal documentation compounds this with inconsistent terminology across pages written by different people over different years, outdated pages that still rank alongside current ones with no obvious signal distinguishing them, and no structural signal for which pages are authoritative versus abandoned drafts.
| Search property | General wiki search | What is actually needed |
|---|---|---|
| Ranks by relevance | Poorly | Well |
| Distinguishes current from outdated | Not at all | Explicitly, via metadata |
| Handles terminology variation | Poorly | Well, or provides synonyms |
| Surfaces the most-used answer first | Not at all | Ideally, yes |
What Meaningfully Improves This
A internal developer portal purpose-built for technical documentation, rather than a general wiki repurposed for it, typically provides materially better search because it is designed around the specific structure of technical content — API references, runbooks, service documentation — rather than generic freeform pages.
Tagging pages with an explicit last-reviewed date and requiring periodic review is a low-effort intervention with outsized impact, because it lets both search ranking and the reader themselves distinguish current guidance from something nobody has touched in three years, which is the single most common reason people distrust and route around documentation search entirely.
Embedding documentation search directly into the tools people already use — the IDE, the CLI, the ticketing system — captures the moment someone has the question, rather than requiring a deliberate context switch to a separate portal that adds enough friction that many people skip searching altogether.
Measuring Whether Documentation Is Actually Working
Track search queries that return no useful result and treat them as a backlog of documentation gaps, since this is a far more direct signal of what to write next than guessing at what people probably need.
Track “asked a colleague instead of searching” as a real signal worth collecting deliberately through short prompts or surveys, because it directly measures the gap between what exists and what gets found, which page-view counts alone cannot reveal.
The Bottom Line
Treat documentation discoverability as a distinct problem from documentation completeness, and invest specifically in search quality, review-date metadata and embedding search into existing tools. Track failed searches as a documentation backlog, because the limiting factor is very often not what has been written but whether anyone can find it when they need it.
