Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Guidelines for writing alternative text

Updated on January 21, 2021

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 of or 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 Picture.
  • 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 alternative text for a screenshot

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 alternative text for a diagram

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 for a chart

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 image and 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.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us