docs: new accessibility page #1418
Conversation
thulieblack
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-1418--asyncapi-website.netlify.app/ |
Co-authored-by: Alejandra Quetzalli <[email protected]>
|
|
||
| ### 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. |
There was a problem hiding this comment.
| - Always use an external link icon if a link opens up in a new tab. | |
| - Always use an external link icon if a link opens up in a new tab. |
Why should we use an external link icon if a link opens up in a new tab? Source and reasoning? Want to make sure this is advice we actually believe 🤔
| ### 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. |
There was a problem hiding this comment.
- Use SVG instead of PNG or JPEG. It retains quality.
In theory agreed... but is this actually something we practice in our docs? So far, I have not seen us use SVGs on our website (or docs). I would remove this line if it is incorrect.
| ### User Interface (UI) | ||
| - Use the correct terminologies for UI elements. | ||
| - Format tables correctly and keep the text within the grid. | ||
| - Use basic HTML for button elements. |
There was a problem hiding this comment.
| - Use basic HTML for button elements. | |
| - Use HTML syntax for button elements. |
- What is
basicHTML? 😄 Why is a button HTML elementbasic? This word choice is wrong because it conveys an assumption and judgement on poor HTML 😂✌🏽 - Please add a code snippet to illustrate the button HTML element.
| @@ -0,0 +1,42 @@ | |||
| --- | |||
There was a problem hiding this comment.
Your "Accessibility" Style Guide document provides a solid basis for creating inclusive and accessible content! Nice work, per usual, @thulieblack! Here are a few suggestions to enhance clarity and usefulness.
Language
- Include some examples of complex language or technical jargon that should be avoided and how they could be simplified.
Text
- The point about defining acronyms or abbreviations is crucial. However, adding a reminder to define these terms upon their first use in any document might be beneficial.
- "Structure your text in a uniform format" - this point could be expanded to clarify what a uniform format means in the context of AsyncAPI documentation.
Links
- Including guidelines on when and where to use internal vs external links would be helpful. (optional)
Multimedia
- Could you provide examples of good and bad alt text for images?
- Add more guidance on when it's necessary to use images. For example, complex technical concepts might be better conveyed with diagrams.
User Interface
- Clarify what is meant by "correct terminologies for UI elements."
- Add detail on how tables should be formatted.
- The tip about using aria-label attribute when unsure of the icon name is great, but consider explaining the aria-label attribute for those unfamiliar with accessibility practices.
Color usage (missing)
Please add a section on accessible color usage, especially for contributors who might be creating diagrams or other visual content.
There was a problem hiding this comment.
Added more content on the missing sections. How is it now? @alequetzalli
There was a problem hiding this comment.
almost there! just a few fixes left
There was a problem hiding this comment.
Looking amazing so far, thank you for your continued dedication! ✨
Thank you so much for your incredible patience in waiting for me to review your work... interviewing and onboarding the 2023 gsod folks took more of my energy than I anticipated, and I had to put Style Guide tasks in the back burner for a little bit 😬.
| - Structure your text in a uniform format by maintaining consistent structure throughout your docs. Accurately provide clear and concise descriptions of AsyncAPI concepts and elements as referenced throughout the documentation. | ||
|
|
||
| ### Links | ||
| - Use descriptive and meaningful link text. For example, do not use phrases like *click here* or *follow this link* instead use *see*. |
There was a problem hiding this comment.
| - Use descriptive and meaningful link text. For example, do not use phrases like *click here* or *follow this link* instead use *see*. | |
| - Use descriptive and meaningful link text. For example, do not use phrases like *click here* or *follow this link* instead use *see*. |
See..what? To make it descriptive, link text must describe where the link takes them.
Please write a new example 😄
There was a problem hiding this comment.
🤣🤣 you are schooling me on accessibility, and I'm glad I'm learning
There was a problem hiding this comment.
FYI, your branch has conflicts to resolve because we finally merged #1261. ➡️ If I were you, I would open a PR in the |
quetzalliwrites
added
📑 docs
area/docs
Co-authored-by: Alejandra Quetzalli <[email protected]>
Co-authored-by: Alejandra Quetzalli <[email protected]>
This PR adds the new accessibility page under the style guide folder.
Resolve #1244