Introduction

A disability isn't always permanent - it can also be temporary or situational. We want to design our service documentation to make sure all of our users have equal opportunities to access and use it. All kinds of users use our products, and we want them to have a great experience.

The following recommendations are based on the Web Content Accessibility Guidelines (WCAG). They intend to raise awareness towards common formulations and provide preferred solutions to achieve a more accessible documentation set. Also check out the SAP Accessibility Standard for information on how SAP generally ensures accessibility.

Some of these recommendations might not be new to you. They're featured in the people-centric approach, the UA Infrastructure User Guide, the SAP Style Guide for Technical Communication, or might already be a best practice in your team. Still, we saw a need to collect all of these ideas in one place.

Accessibility also includes terminology, such as nondiscriminatory, inclusive language. For more information on that topic, see Bias-Free Language.

Getting Started

You're already taking the first step: getting informed. If you learn about ways to make your documentation more accessible, the methods and best practices will eventually be integrated into your daily approach.

Test it!

In Testing, you can find ways to use screen readers and color filters. Take a step back, imagine you don't know your topics, and experience them in a different way.

information

Top takeaways from these guidelines:

Patterns matter: Consistent, logical patterns make it easier to understand our content.
Time over space (when organizing information): If you're not looking at a screen, "first" and "the following" are easier to understand than "left" and "below".
Don't rely on colors: You should be able to understand your graphic just as well in black and white as in color.
No empty alt text: Explain your graphic in the alternative text or let screen-reader users know that the graphic is explained in the text body.
Test it: Check if you'd understand your own documentation if you were relying on tools preinstalled on your computer.

How can I quickly check if my topics meet the accessibility requirements?

Start small and check for the most obvious pain points:

Add alt texts to any topics that contain images. See the section on alt(ernative) text.
Do a text search for directional language, like "above", "below", "left", "right" etc., and rephrase them. See the section on organizing information.
Take a look at topics that describe complex actions - it's more likely that instructions are less accessible than a description of a concept. See the section on describing actions and objects.
If you need to prioritize, focus on your most popular topics. Use analytics to find your most-visited topics.

Guidelines

These guidelines cover the following topics:

Organizing Information
Describing Actions and Objects
Graphics & Other Media

Organizing Information

The way we organize information can make it easier to be consumed and understood.

Be concise. Short, simple texts are easier to consume than long, complicated ones.
Be consistent in definitions and interaction patterns. If we're familiar with a pattern, the content is easier to understand.
Structure your text with headings and format them as such.
Provide a descriptive link text to make a link's purpose clear. Screen readers usually inform the reader if a word is a hyperlink, so the words “click here” or “link” get in the way.
Introduce lists, tables, and graphics with an introductory sentence.
Use column or row headings for tables to easily structure its content.
Organize thoughts chronologically, not spatially. If interfaces are organized around time instead of position (e.g., “after” instead of “below”), it's easier for people who rely on screen readers or magnifiers.
Think of your topic as being a timeline instead of a map. Avoid directional language like "above" or "on the left".

<div> <div>Recommended</div> <div>Not Recommended</div> </div> <div> <div>For more information on linking, see the blog "".</div> <div>Click to learn more about linking.</div> </div> <div> <div>...the details provided in the table...</div> <div>...the details provided in the table ...</div> </div> <div> <div>, choose ...</div> <div>side of the screen, choose ...</div> </div> <div> <div>, review your changes...</div> <div>of the dialog, review your changes...</div> </div> <div> <div>The graphic...</div> <div>The graphic ...</div> </div>

Describing Actions and Objects

Describe the interface in terms of actions and tasks, not component color or visual design.
Avoid referring to objects by color (or by location) alone. Instead, refer to these by their names or by the grouping in which they belong.
Don’t rely on visuals alone to communicate. In tutorials, screenshots shouldn't overshadow the steps, but instead support your textual instructions in complex situations. Also, the visual metaphors of emojis and icons can have a wide variety of interpretations, especially across cultures, so use them with caution.

<div> <div>Recommended</div> <div>Not Recommended</div> </div> <div> <div>Choose</div> <div>Choose the green button</div> </div> <div> <div>Enter email</div> <div>Type email address</div> </div> <div> <div>Save; edit</div> <div>The “Save” button; the pencil icon</div> </div> <div> <div>Menu</div> <div>Side drawer</div> </div> <div> <div>Select, choose, go to</div> <div>Click, tap</div> </div>

Graphics & Other Media

If you design a new graphic, don't rely on color alone to distinguish objects. See Simple Graphics.
Introduce the graphic by using an introductory sentence and/or a title.
Try to avoid redundancies: if the introductory sentence is the same as the title, pick one.
Explain the graphic. If the explanation isn't already part of the text body, put it in the alt text.
Don't leave the alt text empty - even if you explain the graphic in the text body.
A sentence like "The graphic is explained in the accompanying text" is enough to let screen-reader users know that there's a graphic and that it will be followed by an explanation.

Alt(ernative) Text

Alt text is a textual alternative for non-textual graphics. Screen readers read out the alt text so that users get all the information that they need.

When writing alt text, keep the following in mind:

Use active voice to keep the text simple and natural sounding.
Use normal grammar and punctuation. Always ending with a period gives screen readers a signal to pause.
Avoid writing “graphic of” or "the graphic shows". With screen readers, it’s apparent that an element is a graphic. For specific types of graphics that visualize information, like charts or diagrams, or screenshots, it's fine.
Avoid abbreviations. Write the full name.
Write in the order in which you or a screen reader would read the components in the actual graphic or UI. If the graphic consists of multiple smaller components, start at the top left and go from left to right and top to down.
Write about actions and their effects when describing a process. Describe what buttons do, not what they look like.
Include any text that’s part of the graphic. Screen reader users won't be able to consume the text otherwise.
If an image is purely decorative, indicate that in the alt text. For example, add the word decorative before you describe the image.

Having trouble writing a good alt text?

For more best practices, see Alternative Text / <alt> Text in the UA Infrastructure User Guide.

<div> <div>Recommended</div> <div>Not Recommended</div> </div> <div> <div>Alt=”In a black and white photo, a smiling young woman with dark hair is wearing sunglasses.”</div> <div>Alt=”woman in a photo”</div> </div> <div> <div>Alt=”In a user account, there are two user types platform users and business users. Platform users can deploy, administer, and troubleshoot both services and applications in their subaccount. Business users can only use applications in the subaccount.”</div> <div>Alt=”The graphic shows two big gray boxes labeled "User Accounts" and "Subaccount". In the first box, there are platform users and business users, and in the second, there are services and applications.”</div> </div> <div> <div>Alt="Detail of the Scheduler tab for Timer Start, with the option Run Once selected."</div> <div>Alt="A SUI of a screenshot with two tabs for Timer Start. The second tab, Scheduler, has three options, the first of which is called Run Once. This option is selected."</div> </div>

Example: Alt Text for a Graphic

See previous table (second row) for explanation.

Example: Alt Text for a Screenshot / Simplified User Interface Graphic

See previous table (third row) for explanation.

Image Maps

Image maps use hotspots to make your graphics interactive. Users can choose different parts of the graphic and get more information in a separate topic or next to the graphic.

When a text features an image map, screen readers rely on tool tips, alt texts, and surrounding texts to communicate its meaning.

For image maps, similar rules apply as for graphics:

Use alt text. See the previous section on alt text.
Use tooltips. Repeat the text from a text box in the tooltip text for the corresponding hotspot. Screen readers can only read out the tooltip text, not the text box.
Use introductory sentences and explanatory texts. Imagine that the graphic isn't there. Is all the information you want to convey still available?

For more detailed information, see Image Maps (aka Interactive Graphics) in the UA Infrastructure User Guide.

Writing alternative text for an image map (in CMS)

Icons

Screen readers can't recognize icons, so you should add a description to make sure there's something to read out.

If you insert an icon in you documentation using the tag, you can use one of the following methods of adding a description:

Use the sap-icon-font-description tag. The description then appears in italics after the icon.
Alternatively, insert a description in the normal text before the icon itself.

If you insert an , the icon requires alt text. Don't focus on what the icon looks like, but on what it does. See the section on .

For more detailed information, see Iconsin the UA Infrastructure User Guide.

Using sap-icon-font - in CMS

Using sap-icon-font - in SAP Help Portal

Using icons as images

Videos

Videos are a challenging medium as they can combine two channels, and . Users of screen readers and hearing aids can profit from a text alternative to the video, but also users who have trouble understanding the speaker in the video.

Text alternative to audio: provide synchronized subtitles (captions) so users can read what is being said at that moment. A full transcript can also include descriptions of the visual presentation.
If you create a video from scratch, you might have to manually write and add captions or a transcript to it. If you use automated captions, make sure that they work properly.
Text alternative to visual: provide audio descriptions so users can hear what is happening.

For more detailed instructions, see Accessibility Guidelines for Video Content in the Accessibility wiki space or Videos in the UA Infrastructure User Guide.

Testing

information

Since our documentation on SAP Help Portal is text-based, this section focuses on tools used mainly by visually impaired users.

Put yourself in the place of your user by using functionalities preinstalled on your computer. While these tools don’t perfectly simulate the experiences of users who rely on accessible documentation, they're a convenient method of testing your output regarding the points outlined in these guidelines.

Screen readers read written texts out loud, which lets you consume not only documents, but also navigational texts without relying on eyesight.

Enable the screen reader by following the path applicable to your system:

Windows 10: Settings > Ease of Access > Narrator > On (shortcut: Windows + Ctrl + Enter)
Windows 11: Settings > Accessibility > Narrator > On (shortcut: Windows + Ctrl + Enter)
Mac: System Preferences > Accessibility > VoiceOver > Check Enable VoiceOver

Color Filter

Use color filters to limit or customize the colors displayed on your screen. For example, grayscale filters show your screen in shades of gray, but there are also other filters, like the red-green and blue-yellow filters, and filters that invert all colors.

Enable the color filter by following the path applicable to your system:

Windows 10: Settings > Ease of Access > Color filters > Turn on color filters (default: Grayscale)
Windows 11: Settings > Accessibility > Color filters > Turn on color filters (default: Grayscale)
Mac: System Preferences > Accessibility > Display > Color Filters > Check Enable Color Filters and select a filter type from the dropdown list