pyRPCPR #139 reorganized the documentation’s information architecture. No new features, just moving ideas to where readers look for them. Here is the reasoning, because IA changes are only controversial when the rationale is invisible.
What changed
- Client adapters got their own section. React, Next.js, Vue, and Svelte guides were buried among general client pages; they are the pages most visitors actually need, each with installation, provider setup, hook usage, invalidation, and links back to runnable examples.
- A dedicated Links section. After v0.13.0 introduced terminating links, link configuration stopped being a footnote of client creation, it earned its own overview plus per-link pages.
- A reference area for FAQ and lookup-style material, separating “teach me” from “settle an argument.”
- An AI resources section collecting llms.txt, MCP integration, and skills, acknowledging that a growing share of “readers” are agents, and they deserve first-class navigation too.
- Server adapter guides show file names as code-block titles (
title="main.py"), so multi-file walkthroughs stop requiring prose to track which file you are editing.
The principle: match the mental model, not the org chart
Users don’t think “client concepts, then client advanced.” They think “I use Svelte, what do I install?” or “how does batching work?” Sections keyed to those questions convert documentation from linear curriculum into lookup structure. The old sidebar optimized for writing order; the new one optimizes for arrival intent.
Small fixes that compound
The same PR restored sidebar folder icons that a dependency upgrade had silently broken (they rendered invisibly, present, occupying space, painted nothing), removed a stray nav title above the search bar, and deduplicated page headings so anchor links stop colliding. None of these are interesting individually. Collectively they are the difference between a site that feels maintained and one that feels abandoned.
If you maintain docs: audit them like UI. Click every anchor. Resize everything. Ask an agent to navigate your llms.txt. The bugs live exactly where nobody looks.