Guidelines for writing alternative text
When you include images in content, such as screenshots, diagrams, GIFs, or charts, ensure that you provide alternative (alt) text with the image.
Alt text is a short sentence that describes the content of the image and serves the following purposes:
- For reading aloud by screen readers to those with visual or cognitive disabilities or who are unable to view their screens at the time.
- For display as text in place of the image when the image cannot be loaded.
- For search engine optimization (SEO) purposes, by storing keywords, or for various other technical reasons.
Good alternative text
Alt text assists users who are unable to see, or to clearly see, the images. Provide meaningful, helpful alternative text by following these guidelines:
- Do not begin with
An image ofor
A picture of,because most screen readers preface their reading of different elements by stating what that element is, such as
Level 1 heading,
Menu of Links,and
- Keep the alt text to 125 characters or fewer. Many screen readers stop reading after 125 characters. Some read up to 150 at a time, and even continue reading if you press a key, but without knowing which reader software users have, try to stay within the minimum recommended guidelines.
- Use correct punctuation and end the alt text with a period. Screen readers parse sentences as humanly as possible, in a natural, correct way. However, you do not need to capitalize names, and you can leave out complex punctuation, such as hyphens.
- Do not repeat the same information that is in the caption or in the text that introduces the figure. Good alternative text specifically describes the information in the image, not the way that this image is framed within the article as a whole.
- Do not simply stuff keywords and search terms into the alt text, because a string of words is confusing and unhelpful when read aloud.
- Do not leave images without any alt text. Otherwise, screen readers simply read out the file name, which is also confusing and unhelpful.
Good and bad examples
Good alt text: Part of the notification channels landing page that shows a list of configured channels.
Bad alt text: Create notification Notification Channels landing page example
Bad alt text: Picture of the notification channels landing page
Good alt text: Diagram of a next-best-action advisor decision tree showing the hierarchy of next-best-action advisor elements.
Bad alt text: An image of a colorful diagram showing a big decision tree in the next best action advisor
Bad alt text: Pega, Pega Platform, Next-Best-Action Advisor, next best action, strategy
Good alt text: Income over time for the period August 2019 to February 2020. The highest income is achieved in the period August to January.
Bad alt text: Chart showing income over time.Bad alt text: Chart, Income, Dollars, Money, Time
Alternative text in DITA and Drupal
In Oxygen XML Author, you add alternative text by using the
alt element after you insert an image. Alternative text
is rendered in a lighter color than the normal Author view text to indicate that it
is not visible in the output after publishing. For more information about adding
alternative text to images in DITA topics, see the
alt entries in the Common DITA elements topic.
In the Drupal editor for Community, you can access a field for entering alternative text by right-clicking an inserted image. For more information about adding alt text to images in Community articles, see Adding an image to a article.
Previous topic Adding attachments Next topic Hyperlinks and cross-references