Documentation tells you what happened. An index tells AI where to look.
-
Moe Hachem - February 27, 2026
Documentation tells you what happened. An index tells AI where to look. These are not the same artifact and treating them as equivalent is one of the most expensive mistakes in AI-augmented work.
Documentation is a record. It exists for humans - to understand what was decided, why it was decided, and what happened as a result. It’s written in narrative form. It assumes a reader who can scan, infer, and connect context across a document.
An index is a navigation surface. It exists for retrieval - to give AI a structured way to locate relevant context before executing a task. It’s written in declarative form. It assumes a consumer that needs explicit scope, explicit relationships, and explicit pointers to where more detail lives.
When teams try to use documentation as AI context, three things happen:
- The model consumes large amounts of text to locate a small amount of relevant information. Result? Token overhead is high, and precision is low.
- The narrative structure of documentation, which is designed for human inference, produces ambiguity for AI retrieval. Implication doesn’t survive context compression well.
- Documentation grows in one direction: backward. It captures what happened. An index is maintained forward, updated as the system evolves, scoped to current state.
The SR-SI methodology makes this distinction structural. Documentation exists and is valuable, but the index is a separate artifact built specifically for AI navigation - shallow at the top level, deep at the scope level, linked rather than monolithic.
The analogy that holds up: The difference between giving someone an encyclopedia and giving them an index to the encyclopedia. Same underlying information, but with a completely different level of usability.
Your team has accumulated knowledge, so the question isn’t whether to document it, but whether AI can navigate it - and documentation, however thorough, doesn’t answer that question.
Building the index is a distinct, specific act. It’s also the thing that changes every downstream AI interaction.
