From 71 to 100%: What It Took to Make the Rootstock Developer Portal AI-ready
For a long time, when we talked about good developer documentation, some of the primary questions were simple:
Can a developer understand it?
Can they find what they need?
Does the search work?
Is the navigation clear?
Does the documentation experience make sense?
Those questions still matter. But those are no longer the only questions documentation maintainers need to ask.
Developers increasingly work with AI coding assistants, IDE integrations, and other software that retrieves documentation programmatically. The current llms.txt proposal explicitly describes coding agents using websites and documentation as part of development workflows, while AFDocs is designed around how agents discover, fetch, and consume documentation.
Retrieval is only the first step. Agents may also synthesize, filter, prioritize, and summarize the information they retrieve before presenting it to a user.
That means documentation has another reader.
A machine.
Machines don't experience a documentation site quite the same way humans do.
They care about whether content can be discovered, retrieved, parsed, structured, and consumed reliably.
That became evident for me while working on Rootstock's Developer Portal. In this article, I walk you through how I got the Rootstock Developer Portal from 71/100, Grade C, to 90/100, Grade A, and then to 100/100, Grade A+ on Fern's Agent Score, what was done, the measures put in place to prevent future regressions, and also what I think technical writers and documentation maintainers would need to pay attention to in the AI agent era. This article is particularly useful for technical writers, documentarians, and anyone who works with Docs as Code.
For a more in-depth guide to making documentation AI-ready, see The Comprehensive Technical Guide to Building AI-Ready Documentation Systems.
The starting point
The DevPortal was already a strong documentation platform for human developers; an initial benchmark score of 71% highlighted several areas that needed attention. What works reasonably well for a human reader does not necessarily work for software consuming the same documentation, so we should revisit our assumptions.
A page can look perfectly fine in a browser and still be awkward for a machine to retrieve. A navigation structure can be ideal for humans, yet provide poor discoverability for machines. A documentation page can contain the right information but expose it in a format that creates unnecessary work for a machine trying to extract it.
For example, a rich documentation component can work well in the browser while requiring explicit serialization before its information becomes useful in a plain Markdown representation.
So the question became less about simply writing better documentation and more about how the documentation system exposes the knowledge it already contains.
That distinction changed how I approached the work, and I go into detail about what this looks like in Part 2: The Comprehensive Technical Guide to Building AI-Ready Documentation Systems
Fix machine access before rewriting content
My first lesson was that agent readiness does not have to be a content rewrite exercise.
Some of the highest-leverage work was infrastructural.
We worked on things such as
llms.txt coverage
Markdown availability
Machine-readable content negotiation
Markdown export
Content structure
Generated indexes
Page size
Documentation structure
CI validation
In a later technical deep dive, I go into detail on The Comprehensive Technical Guide to Building AI-Ready Documentation Systems, I will go into more depth: Definitions, detailed examples, how to position and align existing and future content, and CI/CD to prevent regressions.
If the underlying content delivery system makes documentation difficult to discover or consume, rewriting thousands of words is not necessarily the first thing you should do.
The phased build
I approached the work as a phased build rather than one large documentation project.
The first phase focused on foundational machine-access issues, including llms.txt URL handling, machine-facing directives, a post-build correction step, and Markdown content negotiation.
AFDocs remediation
We then worked through specific parity and content-start issues identified by the benchmark.
Markdown counterparts
The next stage expanded Markdown availability across the documentation surface.
Structural work
Generated indices, content structure, and large documentation became part of the problem.
Validation
We added build-level checks and validated the deployed documentation against the production environment.
The important part was the feedback loop:
Find the issue → understand the failure → make the change → build the output → validate the output → evaluate again.
What I personally worked on
As the Lead Technical Writer for Rootstock, I led the agent-readiness build from the initial April baseline through the later milestones.
That included defining the phased build, investigating the benchmark results, designing the approach to machine access and Markdown delivery, implementing key parts of the agent-facing documentation stack, validating the production output, and communicating the milestones.
The implementation work included things such as
Correcting llms.txt generation and URLs
Implementing Markdown content negotiation
Building Markdown serializers for MDX content
Adding generated-index Markdown coverage
Restructuring oversized RPC documentation
Splitting large Markdown exports where necessary
Adding CI verification around the generated agent-facing output
Validating that the production deployment matched the expected state
The contribution record also makes an important attribution point here: This was not a case of a technical writer simply filing documentation tickets for engineers to implement. I was directly involved in designing and implementing the agent-facing documentation changes. Other people contributed reviews, stakeholder input, and validation, and that contribution matters too.
For example, Ezequiel Rodriguez's page-by-page review approach was important during the final push to 100.
That is noteworthy because technical writing work increasingly happens at the boundary between content, engineering, and developer experience.
Milestone 1
The first major milestone moved the portal from 71 to 90%.
That took the DevPortal from Grade C to Grade A on the Fern benchmark.
I shared that milestone at the time, but the score was never the most interesting part to me. I had an 'aha' moment while working through this milestone: many of the changes were about making the existing documentation easier for software to discover and consume!
That included better llms.txt coverage, Markdown content negotiation, Markdown export coverage, and CI guardrails.
Documentation was not just a collection of pages anymore. It was becoming a system in its own domain, and this means documentation teams need to be closer to the system and understand how machines work under the hood.
Milestone 2
The final stretch took the portal from 90 to 100%. The approach was more systematic.
We needed:
Broader Markdown coverage
Machine-readable counterparts for generated indexes
Cleaner serialization
Better handling of large RPC documentation
Validation that the expected artifacts existed in production
That last part sounds obvious, but it is important. See The Comprehensive Technical Guide to Building AI-Ready Documentation Systems. Here is how the system was actually built, which documents how these terms work and how to use them.
A local build that produces the expected result is not the same thing as a production documentation system that actually serves that result.
Success!
The final public Fern result now shows 100/100, Grade A+, with 22 of 23 checks passed and no warnings or failures. It also shows the checks covering Markdown URLs, content negotiation, page size, content structure, URL stability, llms.txt coverage, Markdown parity, and related areas.
That is a meaningful milestone.
But it is also where I think the more interesting question begins.
What does 100/100 actually tell us?
It tells us something useful about the evaluated documentation surface.
It tells us that the site satisfies the benchmark's checks at the time it was evaluated.
It gives us a concrete way to identify structural problems.
It gives a team a shared language for talking about machine readability.
Those are valuable.
But a benchmark is only a benchmark.
It does not prove that an autonomous coding agent can complete an end-to-end development task.
It does not prove improved developer conversion.
It does not prove reduced support volume.
It does not prove business ROI.
It does not prove that every downstream AI agent workflow will succeed.
And it certainly does not mean the documentation can now be ignored.
In fact, the harder work would be to maintain that score and not regress.
AFDocs itself describes the benchmark as a set of checks covering discoverability, Markdown availability, page size, content structure, URL stability, observability, and access. It is not an end-to-end measure of every possible developer or agent outcome.
That limitation is not a weakness of the benchmark.
It is simply important to understand what the measurement is designed to tell us.
The problem after achieving a perfect score
Documentation changes, products change, URLs change, and new pages get added; pages are reorganized or replaced; generated content may change; and search behaviour changes.
That means a documentation system can be excellent today and regress tomorrow.
This was one of the most important lessons I took from the work.
A score tells you where you are. It does not tell you whether you will still be there after the next merge or docs release.
That led me into a different problem known as documentation health.
From agent readiness to documentation health
Once you start looking at documentation as a system, you need more than a benchmark.
You need signals.
You need baselines.
You need trends.
You need ways to notice regressions.
You need to understand whether people can find what they need.
You need to know when important content becomes stale.
You need to know when links break.
If machines are now another consumer, you also need to know when machine access regresses.
That is where my thinking around documentation, health and observability started to develop.
The benchmark gave us a useful starting point.
The maintenance problem gave us the next one.
Key takeaways
There are a few learnings I would take from this work.
1. Learn how your documentation is delivered.
You do not need to become a full-time software engineer. But you should understand enough about your documentation stack to know what happens between source content and the page a developer and agent see.
2. Think about more than the browser.
If your documentation is consumed by search engines, LLMs, coding assistants, or other software, the browser is only one representation of the knowledge.
3. Measure before making assumptions.
The benchmark was useful because it gave us something concrete to investigate. Without measurement, it is easy to spend months improving the wrong thing.
4. Automate what should not regress
If a functionality can be checked deterministically, do not rely on somebody remembering to check it manually after every change.
5. Separate evidence from interpretation
A score is evidence of a benchmark result. It is not evidence of every outcome you might want to associate with that result.
6. Treat maintenance as part of documentation work.
Getting documentation into a good state is one job. Keeping it there is another. Both matter.
Conclusion
I started this work thinking about AI agent readiness. I came out of it thinking more broadly about documentation systems.
That is why I do not think the most interesting question is whether technical writers should "become engineers" in the AI agent era.
I think the more useful question is:
Do technical writers understand the systems through which technical knowledge is discovered, retrieved, consumed, measured, and maintained?
I think we need to.
Resources
Here are some resources that helped me:
A note on AI-assisted coding
I used Cursor and ChatGPT extensively during the implementation as an AI coding assistant. It was useful for exploring implementation options, iterating on code, and speeding up parts of the build.
I prefer stating that explicitly, as it is an interesting part of this project.
It is that a technical writer was directly involved in understanding and changing the system behind the documentation.
