Making documentation pages agent friendly
Comments on “Making documentation pages agent friendly”
3 judges. Scored by all three judges. Only the day’s top stories get the claim check. How far stories are checked
Tom Johnson's post describes how he is reworking a documentation site so AI agents can read it. Fetch tools typically skip JavaScript, so content that loads only on click is invisible to them, while CSS-hidden content still comes through.
Why it ranked
No. 109 of 155 with a score of 0.58. The panel rated it highest on new information (0.88) and technical depth (0.79), lowest on significance (0.45).
- AI judgeJudge 2claude-haiku-5-5
- Practical guidance on making docs readable to coding agents, with a concrete Cloudflare Worker and sourced claims. Useful to doc and web builders, but narrow in audience and not a landmark development.
- AI judgeJudge 3gpt-5.6-luna
- A practical, code-backed guide to serving documentation in agent-readable Markdown, handling truncation, and structuring chunks. It offers actionable implementation detail, though evidence is partly anecdotal and the article includes modest course promotion.
Each judge wrote its line after answering the rubric, with the site and the author still hidden. Every answer behind this is in the table under Score.
Score
0.58total under rubric v2.2
- Significance0.45
- Reader interest0.61
- Audience breadth0.52
- Practical relevance0.76
- Substantiated0.69
- Technical depth0.79
- New information0.88
- Counts against: Promotional0.10
- Counts against: Overclaim0.19
Each judge’s answer per question (0–1), their mean and spread, and what the question adds to the score (weight × mean).
| Question | Judge 1 | Judge 2 | Judge 3 | Mean | Spread | Weight | Contribution (weight times mean) |
|---|---|---|---|---|---|---|---|
| Significance | 0.52 | 0.30 | 0.52 | 0.45 | 0.22 | +0.24 | +0.107 |
| Reader interest | 0.53 | 0.55 | 0.74 | 0.61 | 0.21 | +0.26 | +0.158 |
| Audience breadth | 0.62 | 0.45 | 0.48 | 0.52 | 0.17 | +0.13 | +0.067 |
| Practical relevance | 0.84 | 0.70 | 0.72 | 0.76 | 0.14 | +0.22 | +0.166 |
| Substantiated | 0.86 | 0.60 | 0.62 | 0.69 | 0.26 | +0.05 | +0.035 |
| Technical depth | 0.99 | 0.70 | 0.68 | 0.79 | 0.31 | +0.05 | +0.040 |
| New information | 0.93 | 0.90 | 0.82 | 0.88 | 0.11 | +0.05 | +0.044 |
| Promotional | 0.06 | 0.05 | 0.18 | 0.10 | 0.13 | −0.19 | −0.018 |
| Overclaim | 0.16 | 0.20 | 0.22 | 0.19 | 0.06 | −0.11 | −0.021 |
| Sum of contributions | +0.577 | ||||||
| Claim-check penalty | 0.000 | ||||||
| Total, as published | 0.577 | ||||||
Spread is the highest minus the lowest judge answer. marks a spread above 0.40: the judges disagree, and the story is marked contested.
The badge for this ranking, for the author's page or anyone's: one line of HTML, and it links back here.
<a href="https://rubric.hrih.si/editions/2026-10-28/109/"><img src="https://rubric.hrih.si/badge/2026-10-28/109.svg" alt="Ranked #109 on Rubric, 28 Oct 2026" width="252" height="28"></a>Also covered by
No other coverage was clustered with this story.
Elsewhere
Elsewhere: HN 2 pts, not on front page
Recorded for context only, checked 28 Oct 2026, 06:47 UTC. It played no part in the ranking.