--- title: "Why structured wikis make better AI grounding than raw markdown dumps" description: "An essay arguing that structured wikis make better AI grounding than raw markdown dumps. Also the visual proof of what HTML hosting can do." last_updated: "2026-05-22T12:15:01.171537+00:00" source: "https://miradock.com/a/structured-wikis-vs-markdown-dumps" --- # Why structured wikis make better AI grounding than raw markdown dumps Wikiaig Cookbook·Essay # Why structured wikis make better AI grounding than raw markdown dumps Every team that gives an AI tool access to its knowledge eventually faces the same choice: feed it the pages, or feed it the structure. The difference looks small at the start. It compounds fast. **Filed under** · grounding, retrieval, structure 8 min read The first instinct, when an AI tool needs to know about your codebase or your product or your runbook, is to point it at the existing docs. Drop a folder of markdown into the context. Set up a RAG index over the wiki. Let the agent crawl the docs site. It seems obviously correct: the knowledge is already there, written down, why would you rewrite it? The instinct is correct about one thing — the knowledge _is_ there. It's wrong about the shape it's in. Documentation is a format optimized for the human reading experience: linear prose, narrative buildup, examples placed for pedagogical effect, redundancy where it aids learning. An agent reading those pages doesn't benefit from any of that. It benefits from structure that an agent can navigate by intent — "show me every concept page tagged with auth," "compare the two transport options," "give me only the source claims for this policy." Pages aren't that. Wikis can be. Pages are an artifact of how humans read docs. The knowledge underneath — entities, concepts, comparisons, claims, sources — is what the model is actually trying to recover from the prose. The thesis, in one line ## What "structured" actually means here A structured wiki has three things a raw markdown dump doesn't: **typed pages**, **explicit relationships**, and **a single canonical address for each piece of knowledge**. Typed pages mean every page declares what kind of knowledge it carries. An overview page lays the map of a domain. A concept page defines a single thing precisely. An entity page describes something that exists in the world — a service, a person, a tool. A comparison page weighs alternatives. A source page attributes a claim to evidence. The type isn't decorative; it tells the model reading the wiki what shape to expect, and lets the agent ask _for the shape it needs_, not for "more tokens that look relevant." Explicit relationships mean pages link to each other intentionally. "This concept is defined here. This claim is sourced here. This entity is compared with these two alternatives here." The links carry meaning — they aren't just hyperlinks for navigation, they're the graph the agent traverses when it's trying to answer something hard. Canonical addresses mean every piece of knowledge has one URL. When the model wants to know _what the auth flow is_, there is one auth flow page, not nine slightly-different mentions across a README, a design doc, two blog posts, and a Slack thread. Canonicalization is the single highest-leverage thing structure buys you.[1](#fn1) ## How this plays out in practice Two teams, same product, same knowledge, different shape. Question the agent gets Raw markdown dump Structured wiki "Compare the two auth strategies we considered." Returns relevant-sounding chunks from a design doc, a Slack export, and an outdated RFC. Half-quotes each. The synthesis is the model's guess. Returns the one comparison page that was written for this question, with the actual tradeoffs the team committed to. "What's the source for the 50ms p99 latency claim?" Surfaces the page where the claim appears. The reader still has to guess whether the claim was measured, modeled, or aspirational. Surfaces the source page the claim links to: a benchmark run, a date, the conditions under which it was measured. "Has anything changed about retention since v2.4?" Returns retention-related content from many releases. Sorting "what changed" from "what's restated" is the reader's job. Returns the concept page for retention plus the diff against v2.4 — because typed pages support history with semantic meaning. "Give me everything tagged 'security-critical'." No facility to do this. RAG might surface security-flavored chunks, but the answer depends on how the chunks were embedded. A direct query. The wiki returns the seven pages tagged security-critical, sorted by last-updated. #### The compounding effect The gap in the table above is small for any single question. The gap across thousands of questions, asked by different agents in different sessions over a year, is the whole game. Structure is leverage on every read. ## The cost None of this is free. Structuring a wiki takes more effort than dumping markdown. Every page has to declare its type. Links have to be intentional. Canonical pages have to be agreed on, and the team has to stop scattering the same knowledge across blog drafts and chat exports. There's a real authoring cost up front. The honest answer to "is structure worth the effort?" depends on a single question: **how many times will an agent read this knowledge?** A wiki read by one person, once, doesn't need structure — write a doc. A wiki read by every agent session your team runs, every day, for a year, repays the structuring cost in the first week. The teams that get the most out of WikiAIG are the ones who've already noticed they're answering the same questions repeatedly in chat, in PR review, in onboarding. Those answers — extracted, structured, made canonical — become the wiki. Every future answer starts from there. ## A diagram of the difference Structured wiki vs raw markdown dump Two diagrams showing how an agent retrieves knowledge. The left shows undifferentiated chunks from a markdown dump. The right shows typed, linked pages in a structured wiki. RAW MARKDOWN DUMP chunk chunk chunk chunk chunk chunk chunk chunk chunk no types, no links, just similarity STRUCTURED WIKI OVERVIEW auth CONCEPT tokens CONCEPT sessions COMPARE jwt vs opaque SOURCE rfc-9068 SOURCE bench-q4 Left: an agent retrieving from a markdown dump gets chunks ranked by similarity. The relationships between chunks have to be re-derived by the model on every read. Right: the same knowledge as a structured wiki — typed pages, explicit relationships, canonical addresses. The model navigates intent, not similarity. ## When markdown dumps are the right answer To be fair: structuring isn't always worth it. There are real cases where pointing an agent at a flat folder of markdown is the right call. The knowledge changes faster than anyone could maintain structure for. The corpus is shallow — every "page" is two sentences and a code block. The agent only needs to find things, not synthesize from them. The team using the agent is a team of one, and the structuring overhead would outpace the reading benefit. In any of those cases, skip the wiki, point at the markdown, and move on. #### A test for whether you need structure Ask the same question of your AI tool three times across a week. If you get three different answers — each plausible, none clearly correct — you have a structure problem, not a retrieval problem. More chunks won't fix it. Canonical typed pages will. ## The takeaway An AI tool reading your knowledge is functionally a new kind of reader. It reads at a different scale, with different questions, in different sessions, often through different agents that don't share memory with each other. Optimizing for that reader is the same kind of work as optimizing for a human reader, just with different ergonomics — and the ergonomics happen to favor structure. WikiAIG bets that for the knowledge you ask your AI tools to ground on, the cost of structuring it once is small compared to the cost of paying the unstructured tax on every read for the next two years. The wiki is the artifact. The model reads it. Same wiki, every tool. • • • 1. Canonicalization sounds boring and is in fact the most important property. A wiki where each piece of knowledge has exactly one home means the agent retrieves the same answer for the same question every time — independent of which session, which embedding run, or which crawler last refreshed the index. Most "the AI keeps getting it wrong" complaints trace back to a missing canonical page. ## Source [View original artifact](https://miradock.com/a/structured-wikis-vs-markdown-dumps)