# Adoption Gaps in Standards Are Usually Documentation Gaps ## Claim When a published standard sits at near-zero voluntary adoption among people who already have the underlying skill to meet it, the binding constraint is almost always the documentation, not the difficulty. <!-- atomicity: 1 idea ✓ --> ## Scope & conditions - Holds when the target audience demonstrably has the underlying capability, the standard is voluntary, and failure to adopt is silent rather than actively punished or flagged. - Breaks when the standard requires genuinely new capability the audience doesn't have, or when low adoption is suppressed by cost or enforcement friction rather than by comprehension. - Does not establish that better docs alone would close the gap — only that difficulty is the wrong diagnosis when skill is already present. ## Evidence Jessica Lyschik reports that WordPress's accessibility-ready theme tag sits at roughly 270 of 14,700 directory themes (about 1.5%), even though the requirements assume only HTML and light CSS — skills nearly every theme author already has. Her own re-review of the requirements, a month after they were updated, only made sense to her because of years of independent accessibility learning outside the docs themselves. The requirements state the outcome and the test ("this must be achieved," "here's how to check it") but never the implementation — the specific HTML elements and block configuration that satisfy each one. ## Links - [[WordCamp Europe 2026 MOC]] — the usual explanation when a published standard sits unused among people able to implement it - [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]] — because extends; documentation gaps block both human and machine adoption paths - [[3. Resources/Permanent Notes/Accessibility Enforced at Authoring Time Beats Post-Hoc Auditing]] — because applies-in; the fix for a documentation gap is often moving the guidance to the point of authoring rather than the point of audit - [[3. Resources/MOCs/AI & the Future of Knowledge Work MOC]] — because applies-in; documentation-as-the-bottleneck recurs across developer education contexts in this MOC - [[WordPress Platform Design MOC]] — the most common reason a well-designed surface goes unused - [[3. Resources/Readwise/Articles/Book Review ActivityPub by Evan Prodromou]] — extends: the gap is not uniform — documentation of a live standard goes stale newest-part-first. Eden's review finds the O'Reilly ActivityPub book complete except RFC 9421 HTTP Message Signature verification (Standards Track, Feb 2024), which is exactly what deployed servers now send and where implementers currently get stuck. Light-touch source; one claim, kept here rather than as its own Permanent. - [[3. Resources/MOCs/Documentation & Technical Writing MOC]] — applies-in: the docs discipline map, infrastructure cluster ## Tests / falsifiers - If adding implementation-level code examples to each accessibility-ready requirement measurably raises first-pass review approval rates, the claim holds for this case. - If theme authors who already hold the skill still don't adopt after documentation improves, the binding constraint was something else (incentive, enforcement, or discoverability) and the claim is wrong here. ## Maintenance - Last tended: 2026-08-16 - Next review: 2026-11-16 ## Source - [226 – Jessica Lyschik on Why Accessibility in WordPress Themes Is Easier Than You Think](3.%20Resources/Readwise/Articles/%23226%20–%20Jessica%20Lyschik%20on%20Why%20Accessibility%20in%20WordPress%20Themes%20Is%20Easier%20Than%20You%20Think.md) — WP Tavern Jukebox #226, Nathan Wrigley interviewing Jessica Lyschik at WordCamp Europe 2026.