Accessibility

At AsyncAPI, we strive to make our documentation/content inclusive, accessible, and unbiased to everyone. We encourage all contributors to have diversity and inclusivity in mind when writing. To ensure this, we have provided an overview of general guidelines to follow that will help you write inclusive and accessible documents.

Language

• Be clear and concise when writing. Avoid the use of complex language, technical jargon, and verbose explanations.
• Keep paragraphs and sentences short, simple, and to the point.
• Keep your sentences as crisp as possible, avoid having nested sentences.
• Always maintain a uniform structure. Use descriptive headings and subheadings to make navigation easy.
• Use inclusive language and always keep the reader in mind when writing.

Text

• Use the appropriate heading hierarchy. H1 is used for the main heading while H2 to H6 are used for subsection headings.
• Properly align text for easy readability.
• Avoid using camel case or any unnecessary fonts and formatting.
• Define acronyms or abbreviations and always spell out any signs or symbols.
• Structure your text in a uniform format.

Links

• Use descriptive and meaningful link text. For example, do not use phrases like click here or follow this link instead use Read the accessibility guidelines or Explore best practices for inclusivity.
• Always use an external link icon if a link opens up in a new tab.
• Make sure your links or URLs are valid and redirect to the correct/desired destination.

Multimedia

• Alt text must be clear and descriptive. Not more than 50 characters.
• Always use text rather than images, unless necessary.
• Use SVG instead of PNG or JPEG. It retains quality.
• Provide transcripts and captions for video content.
• Make sure your captions can be translated into various languages.
• Avoid auto-playing media, always provide controls.

UI

• Use the correct terminologies for UI elements.
• Format tables correctly and keep the text within the grid.
• Use basic HTML for button elements.
• Add icons to describe a function. Use the aria-label attribute when unsure of the icon name.