No More Gaslight, Gatekeep, Girlboss: An AI-Ready Docs Strategy

Retro computer mascot with eyes on screen saying "vagueness doesn't scale" with network diagram showing connected nodes

Concerned that your docs aren’t AI-ready?

The cool thing is, tech writers and accessibility advocates solved this problem decades ago. AI can’t effectively parse unstructured text or unlabeled diagrams any better than screen readers can, so if companies care about AI-powered docs, they’re accidentally doing the accessibility work they should have been doing anyway.

The techniques that make diagrams accessible to screen reader users - clear labels, descriptive alt text, thoughtful IA - are exactly the same techniques that help AI produce accurate, meaningful results. “AI tools aren’t introducing new requirements.” The practices haven’t changed, the pitch has.

In This Post

The Accidental Accessibility Win
The Communication Tax Comes Due
Why This Matters
Practices That Serve Everyone
Inheriting Unlabeled Diagrams
AI-Ready Actions (That Are Just Accessibility)
Test AI and Accessibility Tools
The Payoff
Summary

The Accidental Accessibility Win

The proliferation of AI hasn’t invented new and improved software development principles. While companies have historically put accessibility on the backburner, what AI-readiness incentives do offer is reprioritizing principles that have been around for decades. The work is identical, the techniques are identical. The only thing that has changed is the motivation - and I’ll take it.

Whether companies are making docs accessible because they care about disabled users or because they want meaningful AI integration - the end result is the same: docs that serve everyone better. This is what Geri Reid calls “AI accidentally making documentation accessible” - when self-interest aligns with doing the right thing, you get change faster than years of advocacy ever could.

The Communication Tax Comes Due

AI hasn’t exposed unique culture debts, but reinforces stale communication patterns that make every tech worker’s life worse. I’ve experienced engineering cultures that don’t offer opportunities to improve dead-end dialogue. I’ve worked with engineers who couldn’t or wouldn’t explain their work in plain terms in various contexts including, but not limited to:

Vague Slack Messages: “it’s broken” - What’s broken? How?
Cryptic Code Reviews: “needs work” - Which part? Why?
Unhelpful Commit Messages: “fix bug” - What bug? What was the behavior?
Opaque Docs: jargon city graveyard, missing context
Unclear Comms Expectations: assuming everyone shares their mental model

I wasn’t an AI-early-adopter, but I was willing to experiment. My initial response was “cool, this is just like teaching a junior engineer - I have tons of experience sharing info.” But I knew that the stereotypical engineer would struggle with this, because effective prompting requires the same skills they’re rarely incentivized to practice:

Breaking down complex concepts into steps
Explaining the why, not just the what
Providing context, not assuming shared knowledge
Being explicit, not implicit
Teaching, not gatekeeping

The culture rewards coding-in-isolation and gatekeeping information is often interpreted as job security. Docs were someone else’s problem. Explaining anything was unnecessary “hand-holding.” Then AI integrations snowballed and vagueness didn’t scale. No more gaslight, gatekeep, girlboss. If you struggle to explain what you need plainly, you just won’t get useful results.

Accessibility has faced the same road blocks. The communication skills that help you with junior engineers, that make your code maintainable, that make your docs practical - these are the exact same skills that help you effectively use AI.

Communication Pattern	Junior Engineers	Screen Readers	AI Tools	Future-You
Vague, Implicit	Confused, asks lots of questions	Misses context, can’t navigate	Hallucinate, give wrong answers	Forget why you did this
Clear, Explicit	Learn faster, productive sooner	Understand content, navigate easily	Generate accurate responses	Remember your reasoning
“Figure it out yourself”	Frustrated, slow progress	Excluded	Ineffective output	Waste time re-learning
Well-documented	Empowered, independent	Included	Helpful	Saves time

Development cultures that “don’t have time to explain things” are now paying that debt back with interest, except now it’s holding back everyone, including engineers.

Why This Matters

Docs are a system of text, visuals, structure, and metadata that need to serve multiple audiences simultaneously. Creating docs for AI-compatibility reinforces accessibility principles. For example, visuals aren’t decoration, they’re navigation and comprehension aids. Patterns I’m observing across the industry:

Stated Motivation	Actual Practice	Who Benefits
“Make diagrams LLM-readable”	Add descriptive alt text	Screen reader users, AI tools, search engines
“Help AI parse our architecture”	Label all diagram components	Anyone who looks at the diagram
“Improve AI docs responses”	Write clear, structured content	Human readers, AI tools, translation systems
“Enable AI-powered search”	Add semantic HTML and proper headings	Screen readers, SEO, AI tools, distracted skimmers

As Bob Watson says, “the fundamentals persist.” It’s all the same work. Use the AI-wave to reframe it. While companies have budget for AI-readiness, rebrand accessibility work as AI-enablement. You now have a better pitch for getting resources.

Practices That Serve Everyone

I have a zig-zag resume that includes full-stack development and archival work, and both taught me that information systems need multiple access points and that communication clarity compounds:

Software Development Lessons	Archival Work Lessons
Systems Thinking: text, visuals, code, and navigation work together	Information Architecture: non-linear navigation is normal
User Flow Awareness: people don’t follow prescribed paths	Different Users, Different Needs: researchers, donors, and public all need different entry points
Spatial Mental Models: technical concepts often work better visually	Metadata Serves Multiple Purposes: discovery, context, preservation
Teaching and Explaining: if you can’t explain it to a junior engineer, you don’t understand it	Clear Docs: if you can’t explain the collection, no one can use it
Testing Assumptions: verify rather than guess	Accessibility is Foundational: it shapes organization from the start

These principles apply whether you’re serving junior engineers, screen reader users, busy developers, search engines, AI, or future-you that’ll forget all your architectural decisions. Similarly - while looking for a historical recipe from a special collections archive, a researcher is initially seeking the basics: ingredients, measurements, steps - but they also need metadata to confirm that it’s the right recipe. Code comments can work the same way - the code functionality may be visible, but the why needs explanation.

Inheriting Unlabeled Diagrams

You’re more than likely not greenfield developing, but working on highly-specialized or icon-heavy diagrams that weren’t designed with accessibility or AI-readiness in mind. Consider the following approaches:

Path	What You Do	Pros	Cons	Best For
1. Add Metadata	Write comprehensive alt text → add text descriptions below diagrams → create accompanying tables → link to glossaries	Doesn’t require source files, can be done immediately	Doesn’t help people looking at diagram directly, maintenance burden when diagrams update	No source files, no organizational buy-in, need quick wins, blocking users right now - immediate fix
2. Progressive Enhancement	Identify critical diagrams → recreate high-value diagrams with labels using D2, Ilograph, Mermaid, PlantUML, Python Diagrams, Structurizr, → establish standards for new diagrams → deprecate old unlabeled versions	Focuses effort where it matters, creates sustainable practices going forward	Requires organizational buy-in, takes time	Limited resources, want to prevent future problems, blocking users right now - long-term solution
3. Automate Descriptions	Feed diagrams to AI tool → validate and correct output → use descriptions as alt text → iterate over time	Faster than manual work, immediately improves accessibility	AI descriptions may be inaccurate, requires human verification	No source files, many diagrams to process, limited budget/timeline - want quick improvement
4. Accept The Limitation	Document the problem → provide alternative text-based explanations → flag as technical debt → focus on new content	Honest about constraints, focuses effort on preventable problems	Doesn’t help users struggling with current diagrams	Dozens+ diagrams need updating, limited budget/timeline, overwhelmed by scope

Retrofitting is hard, prevention is easier. If you establish standards for new diagrams now - require alt text, descriptive labels, diagram-as-code tools - you have a better chance preventing this problem from compounding. Legacy content can be fixed incrementally while you protect against creating more work for future-you.

“AI-Ready” Actions (That Are Just Accessibility)

Add Alt Text to Diagrams

Current Framing: “LLMs need alt text to understand diagrams”

Accessibility Benefits: Screen readers have benefitted from this since the 1990s; helps AI tools, search engines, and anyone with a slow connection that interrupts image rendering

 <!-- Insufficient -->
 <img src="architecture.svg" alt="">

 <!-- Basic -->
 <img src="architecture.svg" alt="System architecture diagram">

 <!-- Helpful -->
 <img src="architecture.svg" alt="Microservices architecture showing API Gateway routing requests through Auth Service to three backend services: Payment, User Management, and Notifications. Each service connects to its own database instance.">

Label Diagram Components

Current Framing: “AI vision models need text labels to identify components accurately”

Accessibility Benefits: Not just recognizable icons, but explicit labels help everyone - future-you, future-maintainers, anyone unfamiliar with the domain icons

Before	After	Why
AWS Lambda icon only	AWS Lambda icon + “Order Processor”	Clarifies the specific function
Generic database cylinder	Database icon + “User DB (PostgreSQL)”	Specifies both purpose and technology
Arrow between services	Labeled arrow: “REST API calls”	Explains the interaction type

Standardize Commit Messages

Current Framing: “AI coding assistants need context to suggest relevant changes”

Accessibility Benefits: Essential for code archaeology and debugging - helps AI coding assistants, incident responders, anyone using git blame

Consider implementing Conventional Commits. I tend to use Angular’s Commit Message Format in my personal projects.
Add Context to Code Comments

Current Framing: “AI needs to understand intent to generate relevant suggestions”

Accessibility Benefits: Essential for efficient collaboration involving future-you, future-maintainers, AI code review bots, auditors, and anyone debugging unexpected behavior
```
 # Insufficient - what, not why
 # Check if user is admin
 if user.role == 'admin':

 # Helpful - explains the why
 # Admin users bypass rate limiting because they need unrestricted
 # access for emergency operations and system monitoring.
 # Reference `docs/rate-limiting.md` for full policy
 if user.role == 'admin':
```
Note: This topic is also discussed more broadly in Anti-pattern: Lack of Documentation and Comments

Write Semantic HTML

Current Framing: “Structured content helps AI extract information accurately”

Accessibility Benefits: Screen readers navigate by headings, search engines index better, AI tools extract effectively, RSS readers format correctly

 <!-- Insufficient structure -->
 <div class="heading">API Authentication</div>
 <div>Use Bearer tokens in the Authorization header...</div>

 <!-- Semantic HTML -->
 <h2>API Authentication</h2>
 <p>Use Bearer tokens in the Authorization header...</p>
 <code>Authorization: Bearer {token}</code>

Create Descriptive Link Text

Current Framing: “AI needs context to understand where links lead”

Accessibility Benefits: “Click here” has been an accessibility anti-pattern for decades because screen reader users navigate via links; AI tools generate accurate responses, distracted skimmers will get where they need to go
```
 
 For more information, [click here](auth-guide.md).

 
 Visit the [Authentication Guide](auth-guide.md) for implementation details.
```

Frontload Answers

Current Framing: “AI extracts information more accurately when answers come first”

Accessibility Benefits: Inverted pyramid style has been around since Morse code and it helps those moving fast (AI) and those who want to move faster (everyone, because everyone is busy)

 <!-- Buried Answer -->
 ## Timestamp Handling

 Our API uses timestamps in several places. Understanding timestamp 
 formats is important because they affect caching, rate limiting, 
 and data consistency. When you send a request, you should use 
 ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).

 ---

 <!-- Frontloaded Answer -->
 ## Use ISO 8601 format for all timestamps

 **Format:** `YYYY-MM-DDTHH:mm:ssZ`  
 **Example:** `2026-02-16T14:30:00Z`

 This ensures timezone consistency across services and prevents caching issues.

 For details on how timestamps affect rate limiting, see [Rate Limiting Guide](rate-limits.md).

Test AI and Accessibility Tools

Successes can determine docs usefulness, while failures can identify areas for improvement:

Test Type	How to Test	Key Questions
Quick Validation	Attach a diagram, ask AI to describe it	Is the response accurate and helpful? Good: “This shows an API Gateway receiving requests, routing through a Lambda function for authentication, then forwarding to three microservices: Payment Processing, User Management, and Notifications.” Needs Help: “This appears to be an architecture diagram with connected components, but I cannot determine details without more context.”
Screen Reader	Use NVDA, JAWS, or VoiceOver to navigate your docs	- Can you understand diagrams from alt text alone? - Can you navigate by headings? - Do links make sense out of context? - Is the reading order logical?
Junior Engineer	Give your docs to someone new	- Can they understand architecture without asking questions? - Do commit messages explain why? - Do code comments provide context? - Can they onboard without interruptions?

The Payoff

Whether you do accessibility work branded as accessibility, AI-enablement, or good communication, everyone benefits. The beautiful thing about communication work is that it compounds - each improvement helps multiple audiences in ways you might not anticipate:

Practice	Screen Reader Users	AI Tools	Junior Engineers	Future-You
Alt Text on Diagrams	Understand visual content	Parse and explain diagrams	Learn architecture faster	Remember system design
Labeled Components	Know what each part represents	Identify architecture accurately	Understand without asking	Recall component purposes
Standardized Commit Messages	Navigate code history accessibly	Suggest relevant changes	Learn from Git history	Debug faster
Code Comments With Context	Understand code intent when navigating	Generate better suggestions	Understand decisions	Remember your reasoning
Semantic HTML	Navigate by structure	Extract information accurately	Learn proper markup patterns	Maintain markup
Descriptive Links	Understand link purpose	Generate accurate references	Follow docs successfully	Find related info
Frontloaded Answers	Find information quickly	Quote accurately	Get unblocked faster	Solve problems faster

Summary

AI Accidentally Created Accessibility Incentives

Companies that treated accessibility as a “nice to have” are now incentivized to change their tune because AI tools depend on the same practices. The work is similar, the motivation changed.
Communication Debt Comes Due

Engineering cultures that don’t chamption communication clarity - accept untangled abstractions, cryptic commits, and missing context - now struggle with AI tools that can’t read minds. Clear communication compounds. The skills that help junior engineers and screen reader users are the same skills that make AI useful.
Take the Win, Use the Momentum

Whether organizations improve docs for accessibility, AI, or better onboarding doesn’t matter - the end result is transparency that serves everyone better. If your company has budget for “AI-readiness,” use it to do the communication work you should’ve been doing anyway.

When inheriting unlabeled diagrams or legacy content, choose your approach based on constraints: add metadata if you lack source files, progressively enhance high-value content, automate descriptions for scale, or accept limitations while preventing future problems. Retrofitting is hard; prevention is easier. Establish standards now to avoid compounding technical debt.

Test the outcomes. If it works for screen readers, it works for AI. If junior engineers onboard from your docs alone, AI can too.
The Gatekeepers Lost

The culture that rewarded gatekeeping information and coding-in-isolation has hit a wall. AI exposed that vagueness doesn’t scale. The engineers who were already skilled communicators found AI immediately effective. The rest are learning that clarity was never optional.

The question “can AI read my diagrams?” is actually asking: “have I communicated plainly enough that anyone — human or machine — can understand what I’ve built?” The answer benefits everyone, regardless of how they access your docs.

Ubiquitous AI has not unearthed pressing new principles - it’s just a communication reframing that reinforces what companies should have been cheerleading all along. The communication tax comes due eventually, and it’s tax season.