search

w3c / wai-aria-practices

WAI Website Resource for aria-practices guidelines
https://aria-practices.netlify.app/aria/apg/
15 stars 14 forks source link

Revise content for "Help improve this page" section #25

Open s3ththompson opened 2 years ago

s3ththompson commented 2 years ago

The "Help improve this page" section should be updated to better suit APG.

Description

"Please share your ideas, suggestions, or comments via e-mail to the publicly-archived list wai-eo-editors@w3.org or via GitHub." should be replaced with "Please share your ideas, suggestions, or comments via e-mail to the publicly-archived list public-aria-practices@w3.org or via GitHub."

Buttons

  1. E-mail: public-aria-practices@w3.org
  2. New GitHub Issue: https://github.com/w3c/aria-practices/issues
  3. Related GitHub Issues: * see below

Related GitHub issues

For Pattern and Example pages, the Related GitHub Issues link should be the relevant project board, e.g. https://github.com/w3c/aria-practices/projects/8 for Accordion.

For other pages, the Related GitHub Issues link is TBD.

s3ththompson commented 2 years ago

@mcking65 @a11ydoer can you confirm the above copy and the correct email address for APG concerns?

@mcking65 @a11ydoer what should the "Related GitHub Issues" link be for non-Pattern / non-Example pages? Or should we replace that button with a different one for other pages? The visual design of this section is best served by always having 3 buttons (even if the third button changes contextually, based on the page type).

a11ydoer commented 2 years ago

@mcking65 @a11ydoer can you confirm the above copy and the correct email address for APG concerns?

Those are correct, @s3ththompson

@mcking65 @a11ydoer what should the "Related GitHub Issues" link be for non-Pattern / non-Example pages? Or should we replace that button with a different one for other pages? The visual design of this section is best served by always having 3 buttons (even if the third button changes contextually, based on the page type).

I didnot understand "non-Pattern / non-Example page" becaue "related github issues" is in Exmaple page, not in non example page.

I like three button idea. "Browser and Assistive Technology Support" is always pointing the same section of the spec. Therefore, that link can be removed or placed as the separate info, in my opinion.

s3ththompson commented 2 years ago

I did not understand "non-Pattern / non-Example page" because "related github issues" is in Example page, not in non-example page.

@a11ydoer Good catch! You're right that there is not currently a "Related GitHub Issues" in the Example page. If we're trying to come up with relevant buttons, though, it seems like the "Related GitHub Issues" link might still be relevant on the Example page (in addition to the Pattern page) since the project it links to covers both types of content, e.g. "Accordion Pattern and Examples Development Project". Just a suggestion though, we can also come up with a different link if there's something more relevant.

shawna-slh commented 2 years ago

Why remove the "Fork & Edit on GitHub" button? We've found it especially useful for people who want to fix a minor error -- for them and for us! And, for those who want to submit a more substantive change for consideration, it is helpful to do a pull request to have it in context. (p.s. "Fork & Edit on GitHub" isn't exactly accurate and we could change it site-wide)

What is the purpose of potential new button: "Related GitHub Issues link... to the relevant project board"? How often do you think users will go there? Does it make sense as a button, or link in the text before the buttons? Or elsewhere?

Why link GitHub in the sentence? Seems unnecessary complexity, given the buttons go to GitHub, and not sure users will want to go to the top level of the repo directly very often.

even if the third button changes contextually, based on the page type

While acceptable, I'd say that is not ideal. Those 3 buttons are a common design pattern throughout the WAI website, and it could be confusing for some if it changes a lot.

mcking65 commented 2 years ago

@shawna-slh, I agree that we should keep fork and edit, but only for things like typos or minor edits. We don't want people to submit PRs for other types of changes without first raising an issue. It would be nice if we could specify that in the content of this section.

For example pages, we'd ideally like to get the "related issues" link into this section rather than the footer. Each example page is tied to a GitHub project that gathers issues for all the examples related to the same design pattern. It is a good way for users to see whether or not there is an existing issue. Even if no one outside the task force does that, people on the task force do. So, the HREF for the "Related Issues" link depends on the GitHub project associated with the example.

Because the sentence before the list of links includes the email address, which becomes a link, it feels like it is pushing people first to email, which is not our preference.

What if we had a help improve section like:

Help Improve this Page

The APG Task Force welcomes your feedback and questions via any of the following:

  • [Raise an issue in our GitHub repository]()
  • Send email to our public mailing list at public-aria-practices@w3.org
  • [Suggest minor revisions by editing in GitHub and submitting a pull request]()

Note: If you'd like to propose substantive changes, please start by raising a GitHub issue that describes your ideas.

Could something like this work?

For example pages, if we could make this section specific to each example page, that would be even better. I am thinking something like:

Help Improve this Page

The APG Task Force welcomes your feedback and questions. To view previous feedback and open issues related to this example, please review the [GitHub_Project_name](). To provide feedback, ask a question, or suggest a change, you can:

  • [Raise an issue in our GitHub repository]()
  • Send email to our public mailing list at public-aria-practices@w3.org
  • [Suggest minor revisions by editing in GitHub and submitting a pull request]()

Note: If you'd like to propose substantive changes, please start by raising a GitHub issue that describes your ideas.