Topics Map > KB Training

KB User's Guide - General Info - How to Create Accessible Documents

This documents will go over several of the different methods and standards used to make written documentation as accessible as possible.

When creating web content for your KB, it is important to keep in mind all audiences that may view that content. Making sure that your content is accessible to all web users ensures that anyone can view and understand your sites. Not all users interact with the web in the same way, so it is vital that your content is accessible in as many ways as possible. For more information about the importance of accessible content, take a look at Introduction to Web Accessibility.

Making Your Page Layout and Content Accessible

Headings

The highest heading within a KB document should be an H2, the document title is always an H1, so that should not be used within a document. For subheadings below that, H2 should be used, followed sequentially, e.g. H3 then H4.  Here is an example of using headings correctly to display nested content:
  • H1: My Favorite Recipes (Document Title)
    • H2: Quick and Easy
      • H3: Spaghetti
      • H3: Hamburgers
      • H3: Tacos
        • H4: Beef Tacos
        • H4: Chicken Tacos
        • H4: Fish Tacos
    • H2: Some Assembly Required
      • H3: Tuna Casserole
      • H3: Lasagna
        • H4: Vegetable Lasagna
        • H4: Beef Lasagna
    • H2: All-In
      • H3: Crab-Stuffed Filet Mignon with Whiskey Peppercorn Sauce
      • H3: Sun Dried Tomato and Pine Nut Stuffed Beef Tenderloin
Read more about heading markup.
The purpose of headings is for semantic markup, not style. Text size can always be adjusted using CSS. Correct usage of headings is necessary in order for accessibility tools, such as screen readers, to function correctly. 

IncludeDoc/Doc embeds

When adding includeDoc tags, make sure that it does not interfere with page structure in ways that are detrimental to usability. Check doc previews as well as using the live site with exclude from search to make sure that the includeDoc is used in a way that keeps the page structure sensible.

HTML

HTML is the base structure of a page, and as such, must be correct for accessibility tools to work correct. For more details on HTML structure you can read the WebAIM semantic structure guide.

Tables

Markup tables using the <th> element for headers, so that screen readers know how the table is structured. Make sure the tables you have also have sufficient contrast for the borders and that they don't exceed the content box area. Read more about Creating Accessible Tables.

Site Navigation

Keep page organization as consistent as possible between articles, so that when a user goes between articles, the information is presented in a way that makes sense to them. If page layout/navigation differs between pages, it can end up in user frustration, and if a user is using something like a screen reader, only more so. Keep heading layout and link structuring as close as possible in between documents for easy navigation.

Color Contrast

Good color contrast ensures that those with visual disabilities can use your pages. There are two standards for color contrast, AA (4.5:1) and AAA (7:1). you should target AA but AAA is nice to have. You can use a color picker browser extension and then check color combinations for compliance with the WebAIM contrast checker.

Embedded Content

Images and Alt Text

All images should have alt text. When inserting an image, you will be prompted to enter text in a dialogue box. With the exception of images that are purely, alt text should never be left blank. If you are unsure of whether an image needs alt text, this alt text decision tree can help you.
In cases where alt text is needed, it should be descriptive and be about 1 sentence long. You do not need to put "image of.." or "screenshot of..." at the front, as it's redundant. Avoid "keyword stuffing" when choosing a image alt text. Check out this Alt Text for Images Documentation for more information. Screen readers read the alt text instead of the file name, so try to use the text to convey the meaning of the image in its context, not what it literally is.

Examples

Imagine we are writing a guide on how to fix a flat tire on a bike. This guide includes the image below:
 
Closeup of rear flat tire on a bicycle 
 
  • Alt text needing improvement: Image of a bike with a flat rear tire in a parking lot; green background.
  • Better alt text: Closeup of rear flat tire on a bicycle
  • Explanation: The first example is too descriptive and contains extraneous text. The parking lot and background are not important to understanding the meaning of the image in this context.

Now imagine we are writing an article about alternative remote working environments. This article includes the image below:

A table at a coffee shop with an iced coffee, an open laptop with earbuds plugged in, a notebook with a pen, and a cell phone
  • Alt text needing improvement: computer coffee iced shop cold drink earbuds phone
  • Better alt text: A table at a coffee shop with an iced coffee, an open laptop with earbuds plugged in, a notebook with a pen, and a cell phone
  • Explanation: The first example uses "keyword stuffing" instead of describing the image. This is confusing for a screen reader user and forces them to guess what the image actually is.

Links

Link titles should be descriptive of where it leads, and whether it opens in a new tab/window. Best practice is to avoid using titles above links, and then just putting "click here" as the link text. Additionally, avoid opening links in a new tab or a new window, if at all possible. There are exceptions, check out When to open links in a new tab for more information. Some screen reader users tab through links to get a feeling for site navigation, so having easy-to-understand link titles helps keep your pages accessible.

Videos

Videos should not autoplay when embedded, so that they do not confuse and annoy users visiting your webpage. Subtitles or a transcript should also be included whenever possible so those with hearing disabilities can access your content.

Language

Accessible Language 

When writing documents, particularly on more technical subjects, consider your audience, and tailor the language to them. If the purpose of the document is to explain how to do a technically complex task to a user whose understanding you don't know, make sure to avoid using excessive technical jargon. Explain acronyms and other technical terms in a way that the average person can understand. To ensure readability of your documents, one tool you can use is the Hemingway Editor.

Bold and Italics

Avoid excessive use of either bold or italic text. While bold text is useful to set aside important language, overuse can lessen its value. Reserve the use of bold text to provide visual emphasis, direct users to actively interact with a screen element, or press a keyboard key. 
 
Overuse of italics can make a document hard to read, find important information, and be confusing for visually impaired users. Reserve the use of italics to denote text that users need to type, cite credits, or designate certain media.

Code

When inserting code into a document, it's helpful to distinguish it using the <pre> HTML tag, or the preformatted text header. This helps the code stick out if it needs to be copied and pasted by a user, or if it's in the middle of a large block of text. The <pre> tag is also expressed as a heading option in the editor. Example code snippet with the <pre> tag:
String welcome = "Hello";
System.out.println(welcome);

Accessibility Tools and More Resources

[Doc 85611 content is unavailable at this time.]

Creating Accessible KB Content (How-to Video)

If you want a detailed overview of web content accessibility as a whole, this presentation from Kurt Murckstadt from the 2021 KB User Group Meeting goes into far more detail. See the document Creating Accessible KB Content to follow along with the presentation.


Keywords:
accessible, contents, elements, scanning, verifying tool, wave, webaim, problems, issues, accessibility
Doc ID:
112389
Owned by:
Leah S. in KB User's Guide
Created:
2021-07-15
Updated:
2024-07-24
Sites:
KB User's Guide