Introduction
Ally reports have the potential to bring up information about a wide array of issues, depending on the type of item (Word document, image file, html file, etc.). In many cases, when you click on individual items to get detailed information you will see an annotated image, pointing out the issue, what it means, and how to fix it. However, this is not always the case. In particular Ally does not have full guidance on all of the issues it can find within html files.
Example of an Ally report overview
The information in this resource aims to bridge any gaps between an Ally report and your full understanding of an issue. The next few pages deal with files of particular types:
- Word documents
- PDFs
- PowerPoint presentations
- Image files
- HTML files
Word document errors
| Issue | Explanation | How to Fix |
|---|---|---|
| The document does not have any headers | This document doesn't contain any marked-up headings. Headings are important as they provide structure to a document, especially those that consist of many pages. When headers are properly and consistently used, the document becomes much easier to understand and navigate for all users. Sighted users rely on text size and bold to identify different sections, properly coding those as headings allows users of assistive technology to do the same. | In Word, select the text that should become a heading (document title, section titles). Under the Home tab in the Styles group, click the appropriate heading level. If you don't see the heading level you are looking for, click the arrows to browse the full list of preset styles. Always choose "Heading 1" for the title of your document, "Heading 2" for section headings, "Heading 3" for subsection headings, etc. "Normal" is used for paragraph text. Repeat these steps for all the text that should become headings. |
| The headings in this document do not begin at level 1 | The headings in this document don't begin with heading 1 and therefore don't follow a logical order. Having the main heading at the beginning of the document will provide a more logical structure and will make the document much easier to understand and navigate for all users. For standard documents, the title of the document should be Heading 1. |
Open the Word document and change the title of the document to heading level 1. Make sure section titles begin at heading level 2, with sub-sections at heading level 3. Video Demo:Fix Minor Heading Issues (Links to an external site.) |
| The headings in this document do not follow a logical structure | Headings should be hierarchical, starting at heading level 1 for the title of the document, then heading level 2 for the sections of the document, then heading level 3 for subsections, and so on. Heading levels should not be skipped. |
In Word, go to View and open the Navigation Pane. This will allow you to get a quick look at the heading structure. Check to see that the correct sections are nested under their parent section. Ex: Video Demo:Fix Minor Heading Issues (Links to an external site.) |
| This document has contrast issues | This document contains text with low contrast between the text and its background. This can cause the text to be difficult to read, especially for those with low vision, poor eyesight or color blindness. |
Change any light font colors to a darker shade (if using headings, modify the style to save time - open the Styles pane, right click on the heading level and select modify, adjust the color in the ). Video Demo:Improve Document Contrast (Links to an external site.) |
| The document does not have a language set | The document does not specify the language in which it's been created. Certain technologies, such as screen readers, rely on the specified language to determine how to pronounce the document text. |
Click Review > Language > Set Proofing Language. Video demo:Fix Document Language (Links to an external site.) |
| The document does not have the correct language set | This document does not specify the correct language in which it's been created. Certain technologies, such as screen readers, rely on the correct language being specified to determine how to pronounce the document text. |
Click Review > Language > Set Proofing Language. Video demo:Fix Document Language (Links to an external site.) |
| The document's heading structure goes beyond six levels | The headings in this document goes beyond six levels. Most technologies, including screen readers and other assistive technology, are limited to six levels of headings. Going above this can cause these headings to not be represented or read appropriately. | In Word, review your heading structure by going to the View tab and opening the Navigation pane. See if you can reduce the number of sections by using bulleted, numbered, or outlined lists instead. Make sure your headings are labelled hierarchically (heading 3s are nested under heading 2s) and you're not assigning them chronologically (heading 1, then 2, then 3, then 4, 5, etc.). |
| The document has images without alternative descriptions | This document contains images that don't have a description or alternative text. People with screen readers or other assistive devices rely on these descriptions to understand the image content and purpose. Alt text will also display if an image doesn't load - benefitting everyone. | Right click on the image (Shft + F10), select Format Picture, under Properties and Layout open the Alt Text pane, enter text in the Description field (not the Title field) |
| The document has tables that don't have any headers | This document contains tables that don't have or properly specify a header structure. People with screen readers or other assistive devices rely on a correct heading structure to help them navigate the table and match the headings to the data cell. |
Click on the table row that contains the headers. Right click (Shift + F10), open Table Properties. Under Row tab, select "Repeat as header row at the top of each page." Uncheck "Allow row to break across pages." Make sure you're not using tables for layout purposes. If your table doesn't need headings (the top row or first column doesn't serve as a label for the data/info underneath/beside) then do not use a table. Note: Alt text - tables can also contain alt text, you can either add explanatory alt text to your table, or mark it as decorative and describe it in the body text. |
| The document is malformed | These documents are malformed and therefore cannot be opened and viewed by many or even most people. While some technologies might be able to deal with some malformed documents, there's no guarantee that everyone will be able to view the document or that the formatting and content will be as intended. | If you do not have the original source document, you may not be able to fix this problem. If you can open the file on your computer, paste the content in a new document and try to save and re-upload the document. |
PDF errors and fixes
| Issue | Explanation | How to Fix |
|---|---|---|
| The document is scanned but not OCRed | These documents are either entirely scanned or contain pages that are scanned. This means it's an image of a document and the text cannot be accessed by assistive technology. Scanned documents, especially those of poor quality or those containing handwriting, can be difficult to read for everyone. They also have other usability issues such as not being able to search inside the document. | Acrobat Pro will convert the scanned image to text. In Acrobat Pro, under Tools, select Enhance Scan. Make sure Recognize text is selected. The higher quality the scan, the more accurate the conversion will be. If you do not have Acrobat Pro, use Ally. Next to the file, click on the small arrow pointing down to the right of the editing wheel. Select Alternative formats. You can download an OCRed PDF. If you want to go one step further and add headings, paste the text from the PDF into a Word document and add headings. |
| This PDF contains images that are missing an alternative description | An alternative description is a textual alternative for an image. It allows students with visual impairments to perceive the image. Alternative descriptions should be added to all images, including those embedded within PDF, Word, PowerPoint and other documents. | If you have the source document, use Word to add alternative text to the document images. Right click on the image (Shft + F10), select Format Picture, under Properties and Layout open the Alt Text pane, enter text in the Description field (not the Title field). If you do not have the source document, you will need Acrobat Pro to add alt text to the images. In Acrobat Pro, go to Tools. Select Accessibility. From the Accessibility toolbar you can select "set alternate text". You will be taken from image to image and can add alt text or mark the image as decorative. |
| This PDF has no title | PDF titles are used as the document title for a PDF window or tab, making it easier to navigate to the PDF and understand the purpose of the PDF. Often the default is the file name which may not be meaningful/descriptive. | In your PDF viewer, Files > Properties > type a meanfingul/descriptive title in the Title field |
| This PDF has contrast issues | Low contrast can make documents difficult to read. | If you have the source document in Word, start there by changing the font color to improve contrast. If do not have the source document but you have Adobe Acrobat Pro, use the Enhance Scans tool to improve contrast. Tools > Enhance Scans. If you do not have Adobe Acrobat Pro, you may be able to change the contrast with a program like Photoshop. |
| The headings in this PDF do not follow a logical structure ***and you have the original source document in Word | Headings should be hierarchical, starting at heading level 1 for the title of the document, then heading level 2 for the sections of the document. Heading levels should not be skipped. | If you have the source document, use Word to fix the headings. Headings should be hierarchical, starting at heading level 1 for the title of the document, then heading level 2 for the sections of the document. Heading levels should not be skipped. In Word, Click through the headings of the document to uncover any skipped heading levels (e.g. going from heading level 2 to heading level 4). Ex: Heading 1 -Heading 2 --Heading 3 --Heading 3 -Heading 2 ---Heading 4 (change to H3) --Heading 3 |
| The headings in this PDF do not follow a logical structure ***and you do not have the source document | Headings should be hierarchical, starting at heading level 1 for the title of the document, then heading level 2 for the sections of the document. Heading levels should not be skipped. | If you do not have the source file, you will need Acrobat Pro (and not Reader), to alter the document tags. Open the tags pane (View > Show/Hide > Navigation > Tags). Review the tag tree and check the heading levels (H1 = heading level 1, H2 = heading level 2, etc.). You can double click on the tag to change the heading. In Acrobat Pro, double click on the heading tag to change it. <H1> <P> <H2> <P> <H4> (change to H3) <P> (Normal body text should be tagged with <P>) |
| This PDF does not have a language set | In your PDF viewer, Files > Properties > Advanced > select language | |
| The document is untagged | These PDF documents are not tagged. PDF tags are hidden labels that clarify the structure of the document and define what's a heading, paragraph, table, list, etc. Without these tags, PDF documents are essentially just a bag of difficult to distinguish words that can be really hard to navigate and understand for people with screen readers or other assistive devices. | If you have the source document, it is much easier to add headings in Word and save the document as a PDF. Otherwise, you will need Adobe Acrobat Pro to fix this problem. Open the Accessibility tool (Tools > Accessibility). Select "auto tag document". Review the tags to ensure they are in logical order. Always choose "Heading 1" (<H1>) for the document title, "Heading 2" (<H2>) for section headings, "Heading 3" (<H3>) for subsection headings, etc. "Paragraph" (<P>) is used for paragraph text. If there are errors in the tags, double click on them to change the heading level. |
| The document is scanned and OCRed | These scanned documents have been OCRed (Optical Character Recognition). Digitizing printed text through OCR allows users and assistive technologies to extract and search text inside the document. OCRed documents, especially those of poor quality, can still be difficult to read for everyone. | To improve the readability of the document, it is recommended that you add tags. Tags act like headings, allowing users to navigate from section to section. If you have the source document, it is much easier to add headings in Word and save the document as a PDF. Otherwise, you will need Adobe Acrobat Pro to fix this problem. Open the Accessibility tool (Tools > Accessibility). Select "auto tag document". Review the tags to ensure they are in logical order. Always choose "Heading 1" (<H1>) for the document title, "Heading 2" (<H2>) for section headings, "Heading 3" (<H3>) for subsection headings, etc. "Paragraph" (<P>) is used for paragraph text. If there are errors in the tags, double click on them to change the heading level. |
PPT errors and fixes
| Issue | Explanation | How to Fix |
|---|---|---|
| This presentation has contrast issues | This document contains text with low contrast between the text and its background. This can cause the text to be difficult to read, especially for those with low vision, poor eyesight or colour blindness. | Change the slide theme in order to improve contrast between the text and background. |
| This presentation contains images that are missing an alternative description | An alternative description is a textual alternative for an image. It makes it easier to connect the image to its context and allows students with visual impairments to perceive the image. Alternative descriptions should be added to all images, including those embedded within PDF, Word, PowerPoint and other documents. | Right click on the image (Shft + F10), select Format Picture, under Properties and Layout open the Alt Text pane, enter text in the Description field (not the Title field) |
Image errors and fixes
| Issue | Explanation | How to Fix |
|---|---|---|
|
The image does not have a description |
An image description, sometimes referred to as 'alternative description' or 'alt text', is a textual alternative for an image. It makes it easier to connect the image to its context and allows students with visual impairments to perceive the image. Descriptions should be brief and convey the full meaning of the image. They should not be the same as the file name as this is often not descriptive enough. |
An image description should provide a textual alternative to the image so that people with a visual impairment can get an equivalent experience. Descriptions also make it easier for all students to connect the image with the context. Different tools offer different ways of adding alt text (e.g. right-clicking in Word, or when adding an image to a Brightspace item you will be prompted to add alt text, or specify that the image is decorative - see not below). *Note: if an image is purely decorative, or is described in the text, it can be marked as decorative and does not require alt text. |
|
The image can induce seizures
|
These animated images contain flashing or contrasting lights or patterns that can lead to seizures for people that suffer from photosensitive epilepsy, which is a very serious and potentially life-threatening condition. Animated images with these characteristics can be generally unpleasant to look at, even for those not prone to seizures. |
Find an alternative image. Do not use this image.
|
|
The image has text that is not part of the alternative description
|
The image contains text that is not represented in the description or alternative text of the image. People with screen readers or other assistive devices rely on these descriptions to understand the image content and purpose and will not be able to read any text in the image that's not part of the description. |
If this is an image acting as text (like a banner graphic), replace it with actual text. If this is a screenshot that contains text components, just make sure the alt text is descriptive enough to capture the nature of the screenshot. In such cases, this is not a problem that needs to be fixed - you just need to be smarter than the machine (Ally) at determining whether or not it is a problem. |
|
The image has contrast issues
|
The image contains text with low contrast between the text and its background. This can cause the text to be difficult to read, especially for those with low vision, poor eyesight or colour blindness.
|
Upload the image into a program like Photoshop to increase the contrast. Video Demo:Increase Image Contrast (Links to an external site.) |
HTML errors & fixes
| Issue | Explanation | How to Fix |
|---|---|---|
| The HTML content has contrast issues | The HTML content contains text with low contrast between the text and its background. This can cause the text to be difficult to read, especially for those with low vision, poor eyesight or colour blindness. | Change the color of the font and/or background color. User WebAIM's color contrast checker (https://webaim.org/resources/contrastchecker/) to find an appropriate color contrast. You can also use the Brightspace Accessibility checker from the HTML Editor to select new colors while in Edit mode. |
| The HTML content has images without alternative descriptions | The HTML content contains images that don't have a description or alternative text. People with screen readers or other assistive devices rely on these descriptions to understand the image content and purpose. Having a clear description for an image can help everyone better understand the content of the image and how it relates to the context. | Click on the image. Go to the Image Options icon from the HTML Editor. Type the alt text into the alt text field. |
| The HTML's heading structure does not start at the right level | The headings in the HTML content don't begin with the main heading and therefore don't follow a logical order. Having the main heading at the beginning of the document will provide a more logical structure and will make the document much easier to understand and navigate for all users. | On a Brightspace page, the page title is Heading 1. Section titles should begin at heading level 2. Sub-sections should be heading level 3. |
| The HTML content has tables that don't have any headers | The HTML content contains tables that don't have or properly specify a header structure. People with screen readers or other assistive devices rely on a semantically meaningful and correct heading structure to help them navigate the table and understand the meaning of every cell, but it can be beneficial to everyone to have a clear structure in the table. | Highlight the cells of the header row (or column). From the table menu in the rich content editor, select "Cell", then "cell properties". Select "header cells" from the Cell type dropdown menu. Select "columns" (if the headings are by column as below. If it's arranged by row, select rows. If you do both, select both options.) from the scope dropdown menu. Click "Ok". |
| The HTML content has empty headings | The HTML content contain headings with no content. This can cause potentially confusing contentless alerts to screen reader users. | It is easy to accidentally mark the line before or after a heading as a heading. Check your page to make sure any blank lines are normal text and not a heading. |
| The HTML content does not have any headers | The HTML content doesn't contain any marked-up headings. Headings are important as they provide structure to a page. When headers are properly and consistently used, the page becomes much easier to understand and navigate for all users, and provides additional benefits such as the ability to automatically generate a Table of Contents. | For longer pages with multiple sections, adding headings will allow a user to navigate by section. Sighted users can scan for section titles, which are usually bold or larger font. To add headings, in edit mode, navigate your cursor to the section title. In the HTML Editor click on the dropdown menu next to the font size (it is in the top left of the editor and probably reads "Paragraph" to signify it is currently set to paragraph text). Select the appropriate heading level for that section title. On a Brightspace page, the page title is Heading 1. Section titles should begin at heading level 2. Sub-sections should be heading level 3. |
| The HTML content does not have an appropriate heading structure | The HTML content contains headings that don't follow a logical order. All headings should follow a sequential and descending order. Headings are important as they provide structure to a page, especially longer ones. Well-structured and logical headings will make the page much easier to understand and navigate for all users. | On a Brightspace page, the page title is Heading 1. Section titles should begin at heading level 2. Sub-sections should be heading level 3. |
| The HTML content contains links without discernible text | The HTML content contains links with text that is not discernible by a screen reader or is not focusable. People with assistive technologies would be unable to understand the link or navigate to it. |
This is a common problem that usually results from someone deleting link text, but not fully removing the hyperlink. You can usually track down the link by looking for an external link icon that is not associated with any text or falls before hyperlinked text. |
| The HTML content has form elements without a label | The HTML content contains form elements such as input boxes, checkboxes, dropdowns, etc. that are not labelled. People with assistive technologies often require the form elements to be explicitly labeled to understand the purpose of each field and to use the form effectively. | |
| The HTML content has embedded objects without alternative descriptions | The HTML content contains embedded objects that don't have a description or alternative text. People with screen readers or other assistive devices rely on these descriptions to understand the purpose and content of embedded objects. | |
| The HTML content does not have a language set | The HTML content does not specify the language in which they have been created. Certain technologies, such as screen readers, rely on the specified language to determine how to process the content or pronounce the text inside of the page. | |
| The HTML content is missing a title | The HTML content is missing a title. HTML page titles are used as the title for a browser window or tab, making it easier to navigate to the tab and understand the purpose of the tab. | |
| The HTML content has malformed lists | The list (<ul> or <ol>) elements in the HTML content contain inappropriate child elements. This can cause screen readers to read out the definition lists incorrectly. | |
| The HTML content has links or buttons with redundant text | The HTML content contains buttons or links with text that is repeated in the containing image's alternative description. Screenreaders and other assistive devices would therefore read this text twice, which is redundant and potentially confusing. | |
| The HTML content has malformed definition lists | The definition list (<dl>) elements in the HTML content contain inappropriate child elements. This can cause screen readers to read out the definition lists incorrectly. |
Source:
https://sbctc.instructure.com/courses/1578604/pages/ally-remediation-cheatsheet (content is offered under a CC Attribution (CC BY 4.0) license).
