Writing documentation for a machine to read

Internal product documentation is usually written with human readers as the primary audience. The structures and formats that make intuitive sense to a person reading on screen sometimes confuse a machine learning model searching for relevant passages in the text.

We took a client's existing manual and applied one simple organizational rule: clear section headings, one primary idea per section, well-formed tables with consistent column structure. We made zero changes to the actual content or information. The substantive material remained identical.

On the same set of one hundred fifty real-world questions from actual users, retrieval quality improved by twelve points. The model now found the right sections more reliably and extracted requested information with fewer errors and better accuracy.

The underlying information was absolutely unchanged throughout the process. The substantive content remained identical. Only the structural organization and readability improved, yet that benefited both human users and machine-based retrieval systems equally well.

This represents the least glamorous work in any AI project. Nobody writes conference talks about improving markdown structure or reorganising section hierarchies in existing documentation.

It also remains often the most profitable work in the entire project: twelve points of accuracy improvement from merely reorganising sections, without modifying any model or changing any infrastructure components whatsoever.