Making Alt Text Fast: How Twilio Scaled Docs Accessibility with Automation

Making Alt Text Fast: How Twilio Scaled Docs Accessibility with Automation

Alt text, first introduced in RFC 1866, is a descriptive attribute for images in HTML that provides a text alternative when an image cannot be displayed. Providing alt text on images has evolved into a critical part of accessibility ensuring there is enough context for all users, including those who are blind or have reduced vision.

On a documentation site like Twilio Docs, we consider alt text essential for making documentation accessible to every reader – but adding and maintaining alt text at scale can require significant manual effort.

At Twilio, we embrace the Docs as Code philosophy. And embracing that philosophy with our alt text focus while maintaining good image filenames introduced new challenges when we added screenshots and diagrams to our documentation – a single pull request with dozens of new images highlighted how cumbersome and inconsistent this process could become without automation.

This post explains how Twilio’s Developer Education team tackled workflow automation with a combination of automation scripts and carefully constructed LLM prompts, and highlights the productivity and accessibility benefits we saw as a result.

Architecture: Prompt-driven automation for scalable docs

With over 5,000 pages and nearly 3,000 images on our docs site – each image chosen and placed intentionally to enhance understanding – the challenge of maintaining accessible, well-described images and appropriate filenames was growing rapidly. To address this issue? We turned to automation.

The team started with respected accessibility sources: Harvard’s guide for describing content images and Google’s alt text writing tips. These references helped us build a structured prompt for our LLM to generate concise, meaningful image descriptions, while keeping their length under 125 characters and avoiding phrases like “image of...” or “screenshot of...”.

We integrated this into a streamlined workflow:

• A command-line tool powers batch processing and automation for our Docs Platform team, allowing us to efficiently handle thousands of images. It also recommends clear, linter-compliant filenames, replacing any generic or unclear image names in the process.

• A web application we named Docs AI Buddy empowers our content owners, managers, and contributors to review and edit generated alt text before images are added to documentation pages.
• The Docs Platform team leverages these generated filenames and suggested alt texts to automatically update our documentation using a remark plugin that parses the content, identifies image nodes, updates their alt text and filename properties, and writes the revised content back.
• The workflow ensures human review of every alt text record prior to publication and consistently outputs files and image references in a documentation-ready format.

Large-scale productivity wins

And how did our process do? The approach has delivered impressive results.

As of this post’s publication, Twilio has processed 2,734 docs images and added reliable, accessible alt text and high-quality filenames—an effort that would have been extremely difficult if done fully by hand. And the generator’s LLM-powered descriptions also have been accurate: the generated alt text has passed our human review for 99.96% of images (including 100% for our most recent drive); only 0.04% needed tweaks. And we accepted 100% of suggested image filenames.

The human time savings are significant. When we first tried a version of this script in April 2025 on around 150 images, our script processing time per image was 5.9 seconds, and human reviews took an additional 1-2 minutes for approval. Compared to the typical 15-30 minutes required to write, review, and lint alt text and filenames manually, we now estimate our automation runs have saved hundreds of hours across the organization.

We started a major alt text updating drive in April of this year which highlighted the power of this approach. We continued with an alt text and filename updating drive this September. Still, we’ve been conservative with our approach: we had our scripts only overwrite alt text where required, leaving strong, existing descriptions intact and updating only what was missing or inadequate. This approach has ensured both accuracy and minimal content churn while enabling a large-scale refresh in a fraction of the time it would have taken us humans to complete manually: a win for our readers, and for our team!

Accessible docs that scale with your team

Our team was thrilled with our initial results – and we’re even more thrilled to apply this process going forward.

Automating our alt text and image filename generation not only makes Twilio’s documentation more consistent and easier to maintain—it also greatly enhances accessibility. This allows our content teams and engineers to focus on other high-impact tasks, such as creating new content, improving troubleshooting guides, or building new platform features, instead of spending time crafting alt text descriptions or naming thousands of images. Since generating effective alt text and filenames at scale is challenging for humans but well-suited to AI’s strengths in following detailed instructions, this is an excellent approach to leveraging AI within our workflow.

But don’t just take our word for it—check out our Documentation or watch the alt text generator in action in this video:

And of course, check out our Docs and let us know what you think about our image descriptions. Let’s build something accessible together!

Maria Bermudez is a Developer Educator at Twilio. She is passionate about solving technical problems in a pragmatic and practical fashion—lately, this involves a lot of AI for scalability and productivity wins. She can be reached at mbermudez [at] twilio.com or https://github.com/bermudezmt .