In my work, I frequently encounter a common challenge: organizations want to help developers and users access documentation more effectively, but the way the information is written often gets in the way. The core of the problem is a failure to recognize that our audience has fundamentally changed. We are no longer just building for humans; we are also building for machines, especially large language models.
AI researcher Andrej Karpathy recently shared his perspective on this shift, and his insights are critical for any team looking to improve documentation and integrate AI systems. To save developers time, reduce costs, and build better tools, we must serve both human and machine readers at the same time.
Here are five ways to make your documentation more effective for this dual audience:
- Use a single, simple `.md` file instead of a complex, styled site.
- Provide real commands like `curl` instead of vague “click here” instructions.
- Add copy-to-clipboard buttons next to code examples.
- Structure content to be easily scraped, parsed, and reused in AI workflows.
- Remove unnecessary visuals and steps that make automation harder.
I still firmly believe documentation should be clear, readable, and well-structured for its human readers. But that is no longer enough. To build systems for the future, we also need to design with machines in mind. This means making our tools and knowledge accessible not just to people, but also to the AI models that rely on that information to function.