March 31, 2026 · Ed Grzetich
What's Inside the Book
15 chapters, 5 appendices, and over 21,000 integration tests. Here's what Tokens Not Jokin' covers, chapter by chapter.
Part I — The Problem
Your docs have a new audience
46% of code is now AI-generated. Your documentation is being consumed as tokens, not as web pages. And most docs teams have zero visibility into how well their content works for AI tools.
CHAPTER 1
Who's Reading Your Docs Now?
AI coding tools are the fastest-growing consumer of your API docs. What that means for how you write them.
CHAPTER 2
The Token Budget
Every token your docs consume is a token the model can't use for reasoning or code generation. YAML describes the same API using ~80% fewer tokens than OpenAPI.
CHAPTER 3
The Measurement Gap
Page views, CSAT, and support tickets are blind to AI consumption. What you should measure instead.
Part II — The Experiment
Two control APIs. Four formats. Four models.
Popular APIs are all over the training data, so any test you run with them is contaminated. We built two APIs from scratch, documented each in four formats, and ran over 21,000 integration tests.
CHAPTER 4
Building a Fair Test
Why we built APIs from scratch. The contamination problem and how control APIs solve it.
CHAPTER 5
The Models
From 3.8B parameter models you can run on a laptop to frontier cloud APIs. Why we chose these four.
CHAPTER 6
The Results
Pass rates, code patterns, and the variance finding. Documentation format explained over 10x more variance in generated code than model choice.
CHAPTER 7
The Four Formats
YAML, OpenAPI 3.0, DON, and Markdown tested head to head. How each performed and why.
CHAPTER 8
DON: A New Kind of Documentation
A novel format that controlled AI code patterns 100% of the time on cloud models. Documentation as a code quality control mechanism.
Part III — The Practical Framework
What to do with the findings
Research is only useful if you can act on it. This section gives you a decision framework, a testing methodology, and optimization techniques you can apply to your own documentation.
CHAPTER 9
Choosing Your Format
The decision framework for your team, your use case, and your audience.
CHAPTER 10
Building AI Acceptance Tests
Set up a testing pipeline in an afternoon. Test whether AI can actually use your docs to write working code.
CHAPTER 11
Token Optimization Techniques
Reduce your documentation's token cost without rewriting everything.
CHAPTER 12
Serving Docs to AI
How to deliver documentation for AI consumption. llms.txt, format selection, and delivery strategies.
Looking Ahead
What we know and what we don't
CHAPTER 13
What the Data Shows
The complete findings, consolidated into a single reference.
CHAPTER 14
What We Don't Know Yet
Open questions, limitations of the research, and where the data stops.
CHAPTER 15
What Comes Next
Where documentation and AI are heading.
The book also includes five appendices: the complete test methodology, all four format specifications, the DON specification, full results tables, and a verified claims reference.
Who it's for
If you write API documentation, this book shows you how your format choices affect what AI tools produce. If you manage a docs team, it gives you a testing methodology and a decision framework. If you run an API platform, it explains a cost your customers are paying that you've never measured.