Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: new accessibility page #1035

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: new accessibility page #1035

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2550c87
Create accessibility.md
thulieblack Jan 29, 2024
c3d6098
Merge branch 'asyncapi:master' into accessibility
thulieblack Aug 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions docs/styleguide/accessibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: Accessibility
description: This style guide explains how to include accessibility in the documentation.
weight: 20
---

# 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.

## 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.
- 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 *see*.
- 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 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.
Loading