Aha! Roadmaps | Knowledge base accessibility best practices

Your knowledge base is an essential resource for your audience, but its true value is bigger than the information it contains. Its accessibility greatly influences its potential impact. An accessible knowledge base ensures that your visitors — regardless of their abilities — can access information.

Focusing on accessibility leads to clearer, more concise, and better-structured content, which benefits all knowledge base visitors. This article provides best practices you can implement to keep your knowledge base's content accessible to all who need it.

Click any of the following links to skip ahead:

• Technical accessibility features

• Structure and formatting

• Voice, tone, and style

• Link text

• Color and contrast

• Roadmaps, reports, and graphs

• Images, audio, and video

• Other resources

Technical accessibility features

Your knowledge base comes with built-in accessibility features. Each knowledge base:

• Is compatible with contemporary screen reader applications

• Is accessible by keyboard navigation

• Is compatible with dark mode

• Uses the contrast ratio recommended by the World Wide Web Consortium's (W3C) Web Content Accessibility Guidelines

If you have a question about technical knowledge base accessibility features, contact our Customer Success team.

Top

Structure and formatting

Information is much easier to consume when it is logically structured. The better your content is to navigate, the easier it is for all knowledge base visitors to retrieve the information they need. Here are some simple structure and formatting tips to make an article more accessible:

• Use headings and subheadings to organize information. This is helpful for visual readers when they are scanning the page. Behind the scenes, headings are also semantic HTML elements that communicate structure to assistive technology.

• Include a table of contents. This helps visitors quickly find and navigate to the content they need. You can use the built-in Table of contents tool included in the Aha! text editor's More options button. Alternatively, you can use any headings you added as anchor links.

• Use numbered and bulleted lists. Lists present steps in a sequential order, helping readers follow instructions more easily. They are also easier for screen reading applications to navigate.

Top

Voice, tone, and style

Your brand has its own unique voice, tone, and style — and you need to balance all of this with instructional clarity. Keep the following accessibility best practices in mind when writing knowledge base articles:

• Use plain language. Simple, concise sentences are best for reading comprehension and can make your content more accessible to visitors of all reading levels.

• Write in active voice. Active voice reduces cognitive load, makes translation easier, and is more compatible with screen reader applications.

• Use inclusive language. Show respect to your knowledge base visitors by being conscientious of the terms you use.

Top

Link text

Your knowledge base is a place of learning and exploration. You might want to link to other relevant information in a knowledge base article that will enhance understanding of an article's topic. But if the link's text is not descriptive enough, it can cause a poor experience.

Avoid using vague link text (like "click here"). Instead, use descriptive link text that signals where the link will take the reader.

Link text is one of the many factors search engines consider when ranking websites in search results. Vague link text could harm a public and indexable knowledge base's visibility in search engine results.

Top

Color and contrast

Poor color contrast makes content difficult to read for knowledge base visitors with colorblindness or visual disabilities. Be mindful of the heading colors you use and ensure they contrast enough with your background to be readable.

Your knowledge base is compatible with dark mode. This accommodates people who might be more comfortable reading with dark mode toggled on.

Top

Roadmaps, reports, and graphs

Reports and roadmaps can be visually complex. If you include a roadmap or report in your knowledge base, provide a summary of the data alongside it so readers with visual disabilities do not miss out on important information.

Top

Images, audio, and video

Including embedded media in your knowledge base is a great way to add context and clarify meaning. But when that media is essential to understanding a concept, you do not want to leave visitors with visual or auditory disabilities behind. There are several things you can do to make multimedia more accessible in your knowledge base:

• Add alt text to all images in your knowledge base. Without alt text, screen reader applications cannot interpret what an image is about (meaning they cannot explain what the image contains to users with visual disabilities).

• Publish transcripts alongside all audio and video media. This makes sure visitors with auditory disabilities can access the audio or video's content. This is also helpful for visitors who are not native speakers of your knowledge base's language, as they can translate the transcript for easier comprehension.

Top

Other resources

• Learn more about web accessibility at w3.org, which is home of the W3C's Web Accessibility Initiative (WAI). The WAI develops standards and resources for making websites more accessible to people with disabilities.

• Learn more about web accessibility from the Americans with Disabilities Act.

• Learn more about inclusive language from the American Psychological Association.

Top