4 mistakes people do when they write alt text

If you've added any image to a website, I'm pretty sure you've been pestered by your UI framework, or your mentor, to add an alt text. And it makes sense. The alt text you do something that a computer alone cannot: turn a picture into words. Words that can be used to count towards your site's SEO and also, to have the image being described by screen readers for people who need it.

Choosing an alt text sounds easy right? Just look at the picture and write what you see. However, there are cases where the text isn't quite right. Here are four mistakes I've seen people make when writing image descriptions:

1. Giving more detail that what is present in the image

Suppose you're writing about symbolism in different cultures and you add an image of "Om", a symbol from Hindu religions.

Now for alt text, you might be tempted to add some detail beyond what's visible in the image:

The symbol for "Om". "Om" is the sound of a sacred spiritual symbol in Indic religions. The meaning and connotations of Om vary between the diverse schools within and across the various traditions.

This is great and all, but think about the expectations of your users, especially those who rely on alt text to make sense of your page. They expect an exact description of your image. Nothing less, nothing more. Avoid confusing your visitors by including any further detail as part of your post.

2. Calls to action

Now let's go back to that "Om" image. Suppose you have a link to the Wikipedia article covering the symbol. Of course you'd like to let people know that you've got a link to learn more. You might think that a good idea is to include instructions on how to get there:

The symbol for "Om". To learn more check out the link for the Wikipedia article at the bottom of the article

Similarly to what we discussed above, however, the last place your visitors want to have calls to action, is on an image's alt text.

Exception

There is however an exception to this rule. Suppose you have an image which is within an <a> link:

<a href="https://en.wikipedia.org/wiki/Om">
    <img src="./om.png" alt="Om symbol"/>
</a>

The alt text works as the link's text in this case. You'll want your text to be the action that the link performs:

<a href="https://en.wikipedia.org/wiki/Om">
    <img src="./om.png" alt="Go to the Wikipedia article for Om"/>
</a>

3. Pasting code in the alt text

This commonly happens when Twitter posts or threads contain images of code snippets, usually from Carbon. Take this post as an example.

If we inspect the HTML code for the image, we see the entire code block being lasted as an alt text:

<img alt="// works but a lot of code const array = [1, 2, 3, 4, 5];

const firstValue = array[0];
const secondValue = array[1|;
const thirdValue = array[2];

// destructuring saves you a lot of code
const array = [1, 2, 3, 4, 5];

const [firstValue, , thirdValue, ...rest] = array;" draggable="true" src="https://pbs.twimg.com/media/FMtSnpvX0AUKRN1?format=jpg&amp;name=large" class="css-9pa8cd" />

Although, this seems like a good idea - after all, it describes the contents of the image, perfectly - but it's not. Imagine someone reading an article to you and reading every little character in the code. It gets a bit annoying after a while.

A better tip would be to have link to a Gist in your post as an accessible alternative. Example

4. Gist URLs

Another thing I've noticed people do when they post code snippets as images, is to create a Gist and them add a link to it in the alt text.

Take this post as an example

Inspecting the image, we can see this:

<img alt="Accessible gist here: https://gist.github.com/emmabostian/a1387fc7da212ee99075169be9f13870" draggable="true" src="https://pbs.twimg.com/media/EouSbjPU0AMBTHv?format=png&amp;name=small" class="css-9pa8cd">

Notice the alt text:

alt="Accessible gist here: https://gist.github.com/emmabostian/a1387fc7da212ee99075169be9f13870"

Although it's great that there's an accessible Gist available, putting it in the alt text, doesn't serve much purpose. Even if the link is there, there's no way for screen reader users to click on it and being taken to the Gist.

Add your Gist link in the post itself instead.

Conclusion

Adding alt text to your images sounds simple enough. Just describe the image in front of you. A lot of the times, this will lead to mistakes that can confuse users who rely on image descriptions to make sense of your content. Be mindful and careful of your descriptions.