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
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.
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 is the base structure of a page, and as such, must be correct for accessibility tools to work correct. Use an HTML Validator to check your code before publishing docs, as long as the page contains no confidential content. For more details on HTML structure you can read the WebAIM semantic structure guide.
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
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.
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.
All images should have alt text. When inserting an image, you will be prompted to enter text in a dialogue box; do not leave it blank. Alt text should be descriptive, and be about 1 sentence long. You do not need to put "image of.." or "screenshot of..." at the front, 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, not what it literally is.
Example alt text: A bike with a flat tire
Example of bad alt text: Image of a bike with a flat rear tire in a parking lot; green background.
Is too descriptive, contains extraneous text (image of meaning can be conveyed in fewer words)
Bad alt text: computer coffee iced shop cold drink earbuds phone
Keyword stuffing instead of describing the image
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 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.
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.
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";
To check pages for accessibility, you can use a tool called WAVE. In order to use it, simply put in a URL to a public page, and it will tell you any possible accessibility problems that your page might have. While you can use it at any time, it's best to write your pages for accessibility first and then check for any mistakes with the tool. Check out WAVE here.
If you want to further check your pages for accessibility, you can use the WebAIM Quick reference or the more fully-featured WCAG 2 checklist and make sure that all the elements on the page meet all of the guidelines outlined in the list. Some important ones if you're editing the styling of spaces are color contrast and font sizing. If you edit the colors of a page in a manner that does not comply with AA or AAA standards it can make the page difficult to read for someone with a visual disability. You can check for color contrast using a color contrast checker. If making use of custom CSS or forms take a look at Accessible CSS and Accessible Forms. For more UW specific policy, you can view the official DoIT Make it accessible guides.