Developer & Programmer Playbook

Verify clear content and language and terms are explained or linked to definitions or additional information.

Best Practices

• Compose content at a 7th or 8th grade level, using clear language and short sentences. 
• For long emails, consider a summary at the top, above the details
• Use bulleted or numbered list styles for key points, questions, etc.  (Learn more about Using Lists)

Relates to: WCAG 3.1.5 Reading Level

General best practices(s)

The first time an acronym is used, all words should be written out, followed by the acronym in parentheses. Subsequent instances can use only the acronym.

For example:

The Americans with Disabilities Act (ADA) was passed in 1990.  The ADA was created to protect the civil rights of people with disabilities.

Exception(s)

Abbreviations such as PDF which has become common usage

Content Designers and Application Developers and Programmers best practice(s)

Don't use tooltips, hover, or the <abbrev > tag

Relates to: WCAG SC 3.1.4 Abbreviations

Organizing your information with headings in a document

Use the application's styles to apply headings.

1. Each document (Word, Excel PDF, PowerPoint, etc.) should have only one Title that is descriptive and relatively short; the title of the document
2. Headings should be used in order starting with Heading 1
3. Headings indicate meaning, a change in section or topic, and indicate the information hierarchy
4. Meaningful information should be at the beginning of the heading so the reader gets the clarifying information first (helps cognitive and screen reader accessibility)
   
5. Heading levels shouldn't be skipped
6. Heading styles should not be used for styling text, use the application's styles for changes to the look of the text

Heading examples:

Correctly used headings

• Title: UTMB Disaster Guide
• Heading 1:  Flood preparation
  • Heading 2:  Water storage
  • Heading 2:  Sandbags
• Heading 1:  Fire preparation
  • Heading 2:  Evacuation plan
  • Heading 2:  Fire extinguishers

Incorrectly used headings:

• Title: UTMB Disaster Guide
  • Heading 1:  Preparing for a flood
    • Heading 3:  How to store water
    • Heading 3:  How to store sandbags
  • Heading 1:  Preparing for a Fire
    • Heading 2:  Evacuation plan
      • Heading 4:  Rope ladders
        

• WCAG 1.3.1 Info and Relationships
• WCAG 2.4.10 Section Headings

The text is readable.

1. The font style is clear and easy to read: UTMB uses Minion Pro (if unavailable use Georgia ) or Helvetica Neue (if unavailable use Arial )
   
2. Text size is at least 14pt
3. Any text with color has a clear contrast from the background
   

Color can't be the only way to indicate the meaning of an item.

Example 1

Hyperlinks (links) that are only indicated by a change in text color

Solutions:

• Hyperlinks should be underlined
• Additional affects should be added for focus and hover that do not rely on color alone.  (UTMB is currently adding a second underline.  For example, cards on the this site have a dashed edge on hover)

Example 2

Using green to indicate good, yellow to indicate warning, and red to indicate an error.  A person with colorblindness or low vision will need additional formatting to distinguish between them.

Solutions:

• Use a label for each area in addition to the color
• Use a pattern in the color (such as stripes, or dots) so the meaning can be identified by texture

Relates to: WCAG 1.4.1 Use of Color

The color of text should be have clear contrast (be significantly different) from the color of the background.

Basic verification

• Look at the colors, do they stand out? 
• Check the UTMB Color Palette to see recommended primary and contrasting colors.
• If someone was reading it with low light or without their glasses would it be easy to see?
  

Relates to:

• WCAG 1.4.3 Contrast (Minimum)
• WCAG 1.4.6 Contrast (Enhanced)

Overview

There are two kinds of lists; ordered (numbered) and unordered (bulleted).

Ordered lists

1. Begin with a number
2. Indicate an order or level of importance to each item

Accessibility tip: A screen reader would read this list as, "Ordered lists, list with three items. One, begin with a number. Two, Indicate an order or level of importance to each item"

Bulleted lists 

• Begin with bullets
  
• Items have equal importance

Accessibility tip: A screen reader would read this list as, "Bulleted lists, list with two items. Bullet, begin with bullets Bullet, Items have equal importance"

Remember to

1. Decide which type of list is appropriate
2. If there's an order or importance to each item use a numbered list and list each item in order
   
3. Items are of equal importance; use a bulleted list
4. If there are multiple lists on a page, select the correct format for each list based on its contents
5. If there are multiple numbered lists, be sure to restart numbering for each new list of items
   

Accessibility tips:

• Use the built-in list formatting for each application to create the list so that screen readers will indicate it is a list
• Web content creators and developers - these break the way that screen readers handle lists and shouldn't be used
  • list-style-type: none;
  • display : inline;
    

Relates to: WCAG 1.3.1 Info and Relationships

Overview

Do:

• Avoid one word links
• Create meaningful link text
• Limit links to seven words
• Limit the use of anchor links (cognitive, visual)

Don't:

• Use "click here", "click to", "image of" in the link
• Use the same link text for more than one link
• Change the link formatting from the standard

Hyperlinks (Links) need to be clear and easy to understand. 

• Links should be a few words of text to a phrase

Best Practices

• Short: Links should be under 50 characters
• Unique text: Links shouldn't contain "More," "Read More", "Find out more", "Click Here," or have the same link duplicated on the page
  
• Links should be meaningful and indicate what selecting them will do (go to a page, email someone, download a document, etc.
  
• Avoid text instructing the user to click the link. If absolutely required; avoid using click, instead use select. (Not everyone is using a mouse and can click)

Email links

Recommended:

Email the marketing team

Not recommended:

Email the marketing  team at marketing@example.com

Phone links

Notes: Use hyphens and include the country code.

<a href="tel:18005555555">1-800-555-5555</a>

For more, detailed information, see 3.5.6 Make Telephone Numbers "Click-to-Call"

Relates to:

• WCAG 2.4.4 Link Purpose (In Context)
• WCAG 2.4.9 Link Purpose (Link Only)

What are hashtags?

• Hashtags create an automatic, descriptive label creating a label, highlighting the content's topic
  
• In most applications it also creates a link which activates a filter for other content that has been marked with that hashtag
• This makes content easier to find and increases exposure, sometimes it's also used to make a statement as in #ChangeMakers

Format

• They begin with a # (called a hash or pound sign) to set them apart from the rest of the text, indicating this isn't
• Hashtags should be title case ( #TitleCase) -- capitalizing each word makes it easier to see the division between words, for example in #utinservicetotexas  it is difficult to see each word, adding the capital letters #UTinServiceToTexas, makes a big difference in readability.
• Read over your hashtags, sometimes when the spaces are removed unintentional words form, though using TitleCase helps to limit that.  For example, #webart, our eyes are naturally drawn to "we" which changes "web art" to "we bart" it's clealy #WebArt when you use TitleCase.
  
• Use 5 to 7 hashtags per post

Examples

• #UTMB
• #MentalHealth UTinServiceToTexas #BetterTogether
• #DigitalAccessibility
  
• #Accessibility #Ally  #Tech4Good

NOTE

Some applications will suggest the lower case version of a hashtag, you'll need to manually capitalize them until the applications are made accessible.

Best practice: Send email in HTML format (UTMB default)

Alternate: Send email in Plain Text format

Do not use: Rich Text

Text alignment can affect reading speed and comprehension

• Centered text can be helpful or visually pleasing and a way to organize a page.  Unfortunately, long sections of centered text significantly slow reading speed.
• Block or justified text was originally used in newspapers to make the columns visually appealing.  This is achieved by randomly adding spaces between words to that the last character of a word ends each column.  Because the spacing is different for each sentence this significantly slows reading speed and can cause delayed comprehension
  

Best practices:

• Center short sections of text, primarily use for headings and new sections
  
• Avoid block or justified text
  

Before sharing or posting an image, verify the image follows UTMB guidelines

Image format

The image doesn't contain text (screen readers can't read it and it doesn't always resize correctly)

The file type is correct for the function

• jpg, jpeg - photographs and other images
• .png - when a transparent background is needed
  

The file is under 1MB

Image file name is clear

• Meaningful and relate to the content
• Sentence case or Title Case (avoid all caps except for acronyms)
  
• Single between the words
• No special characters, especially underscores, ampersand,s and quotes)
• Avoid dates and words like final, copy
  

Remember Image alt text

Images should have alternate text added.

Writing a good image description

Describe the image like you would to a person who wasn't in the room with you, so they know what is happening int he image.

• Write in sentence case.
  
• Include just the description, not introductory text like "An image of" or "Image of" as screen readers will say something like, "Image: Image of a red train going through a dark tunnel."
• Indicating the image is a graph, photo, or screenshot is okay. It will often sound like Image: Graph showing the number increase in sales" or "Image: Photograph of Mount Hood at sunset"
  
• Include any text in the image (for example legacy images that haven't been updated)
  
• If the image is complex or needs more of a description, add a detailed caption to the image.
  

Basic verification

• Run the application's accessibility checker.  If the application doesn't have an accessibility checker (or wizard, etc.) Manually verify that each image has a description.
  
• Verify images
  • have alternative (alt) text
  • don't contain text
  • use the file name as the alt text

See also:

Writing effective alt text

Add alt text to an images in:

• Outlook
  
• Word
• PowerPoint
• Excel
• Office graphs, shapes, pictures, SmartArt