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.

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

docs: new accessibility page #1418

Closed
wants to merge 41 commits into from
Closed
Show file tree
Hide file tree
Changes from 24 commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
a4fcd17
create folder
thulieblack Feb 2, 2023
b4d3cf5
Merge branch 'asyncapi:master' into master
thulieblack Mar 9, 2023
d0f37c0
Delete aboutguide.md
thulieblack Mar 9, 2023
732ddbf
new-access-page
thulieblack Mar 10, 2023
81a49eb
Merge branch 'asyncapi:master' into accessibility
thulieblack Mar 10, 2023
2df18ce
Update accessibility.md
thulieblack Mar 10, 2023
bdcac3b
Update accessibility.md
thulieblack Mar 10, 2023
91ca2f4
Create index.md
thulieblack Mar 10, 2023
326c4fc
Create _section.md
thulieblack Mar 10, 2023
cd125fd
Update index.md
thulieblack Mar 10, 2023
0a51abf
Delete _section.md
thulieblack Mar 10, 2023
bc37b86
Create _section.md
thulieblack Mar 10, 2023
8a82cc3
Update accessibility.md
thulieblack Mar 10, 2023
7532223
Update accessibility.md
thulieblack Mar 10, 2023
9ce02cf
Update accessibility.md
thulieblack Mar 10, 2023
1ef949a
Update accessibility.md
thulieblack Mar 10, 2023
1ed0b19
Update _section.md
thulieblack Mar 10, 2023
6597852
Update index.md
thulieblack Mar 10, 2023
186a20a
Update index.md
thulieblack Mar 10, 2023
355bf7b
Update _section.md
thulieblack Mar 10, 2023
8544de7
Update accessibility.md
thulieblack Mar 10, 2023
49a3ddd
Update accessibility.md
thulieblack Mar 10, 2023
fac245f
Create _section.md
thulieblack Mar 10, 2023
746aa12
Merge branch 'master' into accessibility
quetzalliwrites Mar 14, 2023
829d87d
Update pages/docs/community/index.md
thulieblack Mar 15, 2023
3abe479
Merge branch 'asyncapi:master' into accessibility
thulieblack Mar 15, 2023
c0ac0c6
update
thulieblack Mar 15, 2023
27a07b7
update
thulieblack Mar 15, 2023
03fd821
Merge branch 'asyncapi:master' into accessibility
thulieblack Apr 5, 2023
137cacc
Fixed all headers
quetzalliwrites Jun 7, 2023
ea44d39
Merge branch 'master' into accessibility
quetzalliwrites Jun 7, 2023
6435902
Merge branch 'master' into accessibility
thulieblack Jun 12, 2023
69d8be6
add suggested changes and improvements
thulieblack Jun 12, 2023
3389cf6
Merge branch 'master' into accessibility
thulieblack Jun 16, 2023
fb3a3de
Update pages/docs/community/styleguide/accessibility.md
thulieblack Jun 16, 2023
3ca0a22
Update pages/docs/community/styleguide/accessibility.md
thulieblack Jun 16, 2023
a36255d
add proper example for links
thulieblack Jun 16, 2023
281a63c
Update accessibility.md
thulieblack Jun 16, 2023
b78ad0b
Update index.md
thulieblack Jun 16, 2023
5bd2aeb
Merge branch 'master' into accessibility
thulieblack Jun 16, 2023
fd47734
Merge branch 'asyncapi:master' into accessibility
thulieblack Jul 27, 2023
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
4 changes: 4 additions & 0 deletions pages/docs/community/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: 'Community'
weight: 5
thulieblack marked this conversation as resolved.
Show resolved Hide resolved
---
25 changes: 25 additions & 0 deletions pages/docs/community/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
title: Overview
weight: 2
---

## Community: Guidelines and resources around community.

Welcome to AsyncAPI **Community**! Our Community section documents the community guidelines and resources.

<Remember>

## Contribute to the AsyncAPI Community section
Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our [AsyncAPI Docs Board](https://github.com/orgs/asyncapi/projects/8).
thulieblack marked this conversation as resolved.
Show resolved Hide resolved
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

### Docs contributor questions
Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`alequetzalli`](https://github.com/alequetzalli) 🐙.
</Remember>
4 changes: 4 additions & 0 deletions pages/docs/community/styleguide/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: 'Community'
weight: 5
---
42 changes: 42 additions & 0 deletions pages/docs/community/styleguide/accessibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added more content on the missing sections. How is it now? @alequetzalli

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

almost there! just a few fixes left

title: Accessibility
description: This style guide explains how to include accessibility into the documentation.
weight: 20
---

# Accessibility
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

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
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
- 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
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
- 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
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
- Use descriptive and meaningful link text. For example, do not use phrases like *click here* or *follow this link* instead use *see*.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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 😄

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤣🤣 you are schooling me on accessibility, and I'm glad I'm learning

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♥️🔥🔥🔥 it's definitely a mindset change

- Always use an external link icon if a link opens up in a new tab.
Copy link
Member

@quetzalliwrites quetzalliwrites Jun 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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 🤔

- Make sure your links or URLs are valid and redirect to the correct destination.

## Multimedia
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

- 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
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
- Use the correct terminologies for UI elements.
- Format tables correctly and keep the text within the grid.
- Use basic HTML for button elements.
Copy link
Member

@quetzalliwrites quetzalliwrites Jun 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Use basic HTML for button elements.
- Use HTML syntax for button elements.
  1. What is basic HTML? 😄 Why is a button HTML element basic? This word choice is wrong because it conveys an assumption and judgement on poor HTML 😂✌🏽
  2. Please add a code snippet to illustrate the button HTML element.

- Add icons to describe a function. Use the aria-label attribute when unsure of the icon name.