Writing alt text editors will actually fill in

This piece collects what we learned doing it on real client projects, in the order we would do it again. None of it is clever; all of it has saved us time at least once.

Where it usually goes wrong

Most problems are not technical. They come from starting without an inventory, changing several things at once and finding out about a dependency on launch day. Writing the plan down first turns a risky week into a predictable one.

Do the boring part first. It is the part that decides whether the interesting part works.

The checklist we use

• List what exists today, including the parts nobody remembers adding.
• Decide what has to stay identical and what may change.
• Change one layer at a time and check after each step.
• Keep a short log, so the next person does not have to rediscover it.

A small example

Here is the shape of the configuration we start from. It is deliberately minimal; every extra line should have a reason.

imports:
  - { resource: 'EXT:sitepackage/Configuration/Sets/Base/settings.yaml' }
settings:
  website.language: en
  website.cache: aggressive

What to measure

Pick two or three numbers before you begin and compare them afterwards: time to first byte, largest contentful paint and the number of editor complaints in the first week. If none of them got worse, the change was a success.

---

More posts like this live under Accessibility. If you try this on a project of your own, tell us how it went in the comments.