"When we write documentation, we often assume someone will read it top to bottom. Even when we skim, we start at the top, absorb context, build a mental model. And we infer stuff, like if you’re reading design system docs, you probably already know what a design system is.

AI agents don’t work like this. They retrieve the most relevant chunk based on semantic similarity and produce a response from that slice. If the definition is three paragraphs in and the agent retrieves paragraph one, it fills in the gaps.

That’s where hallucination creeps in. You’re absolutely right! Not because the model is careless, but because much of our documentation is structured for narrative flow, not retrieval. It was always fragile, humans were just good at compensating.

Writing for AI agents accidentally makes documentation more accessible. A screen reader user navigating by headings needs the same explicitness an AI agent needs. A new team member needs definitions that don’t assume prior knowledge. A developer working in a second language needs sentences that say exactly what they mean. Explicitness helps anyone who can’t rely on context to fill gaps.

Look at well-documented APIs. The ones that specify exactly what parameters do, what they return, what breaks. They’re used more, trusted more, cause fewer support tickets. Explicitness scales."

https://gerireid.com/blog/ai-is-accidently-making-documentation-accessible/

#TechnicalWriting #Acessibility #TechnicalCommunication #AI #SoftwareDocumentation #AIAgents #APIDocumentation #Markdown

It can’t be said often enough..
And you don’t have to write an essay (although I’m sure a detailed alt text would be appreciated) but please:

👏STOP 👏SHARING 👏PICTURES 👏WITHOUT 👏ALT 👏TEXT!

THEY’RE LITERALLY INVISIBLE TO SOME OF US.

#altText #altTextMatters #acessibility https://fandom.ink/@Fragglemuppet/115243900391391396

I was taken to Wentworth House today for a light luncheon. I saw much of the ground floor, but the family rooms and the ballroom, dining room, breakfast room, library, etc, are all upstairs. The family chapel is on the ground floor but up a step.
I managed to get around 2.5 sides - outside - of the longest house in England (the UK?).
But they have gravel paths ... not great for my mobility scooter battery as rough ground eats up the charge, so I didn't tour any of the gardens.

I would never ask anyone to tear apart a historic building so I could get round it. But there are some less drastic improvements they could make.

The posh afternoon tea, at about £35 a head and all carbs, is unreachable, but then I couldn't afford it or want loads of carbs.

It made me think of Edinburgh Castle, where they made a fantastic job of making so much of it accessible without ruining the buildings.

#Acessibility

Interview #acessibility on #Linux with @TechOverTeaShow was 10/10

> Be proud of the acessibility work that you do. If you're working on accessibility, I want to hear about it, I want to know what you're doing. Even if it's not for the blind, if it's for the hard of hearing, or it's for people with motor issues, people with cognitive issues that have a hard time with focus or memory or whatever it is. I wanna hear about it. Accessibility should be celebrated. Not put on a shelf somewhere to rot.

I'd like to wholeheartedly thank @fireborn for kickstarting a lot of the recent discussion regarding accessibility on Linux. It can be really hard to share and discuss things related to our disabilities. It can be frustrating and extremely painful. The years of fatigue dealing with the same things and not being properly heard can really burn us out. By reaching out and saying it out loud we essentially paint a big target on ourselves for more harassment and discrimination

#acessibility #Linux