aria-practices

aria-practices copied to clipboard

Adds special treatment of examples that are marked 'experimental' as described in #2836.

This PR is currently using fake experimental content and should not be merged until content developed to resolve #3015 is merged into this branch.

The build can be previewed here: https://deploy-preview-310--aria-practices.netlify.app/aria/apg/

Because this is a new content type, the automatic build will not work until the accompanying wai-aria-practices PR 310 is merged.

---

WAI Preview Link failed to build on 'Update site files' step. (Last tried on Mon, 10 Jun 2024 19:42:44 GMT).

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1206547249952263

@howard-e do you know why the tests are failing? The failures do not seem related to the changes in the PR. I tried a few retries but that didn't seem to help.

Hi @mcking65! If you could take a look at the experimental support notice copy, I'm sure you will have a few changes to recommend!

@howard-e do you know why the tests are failing? The failures do not seem related to the changes in the PR. I tried a few retries but that didn't seem to help.

@alflennik you are right that the failure has nothing to do with this PR.

It is the same issue reported in #2938. I haven't spent the time to investigate why it happens but it is being tracked in the APG's issue triaging process process so your work here should be able to continue with that in mind.

The ARIA Authoring Practices (APG) Task Force just discussed Support for experimental content.

The full IRC log of that discussion

<jugglinmike> Topic: Support for experimental content
<jugglinmike> github: https://github.com/w3c/aria-practices/pull/2977
<jugglinmike> Matt_King: If you follow the preview link, then go to the "index" page and scroll down so you have the very last heading on the page in view
<jugglinmike> Matt_King: It's called "experimental examples"
<jugglinmike> Matt_King: The first pattern we want to get into APG is called "ARIA Actions"
<jugglinmike> Matt_King: We want people to be able to get to ARIA Actions--the people who are working on this, e.g. ARIA-AT Testers
<jugglinmike> Matt_King: Those people will be able to pull up this example which is "not part of the official APG"
<jugglinmike> Matt_King: There are several aspects to the design of this page
<jugglinmike> Matt_King: Every experimental example's title has the word "Experimental" in brackets
<jugglinmike> Matt_King: The "read this first" content is expanded by default (instead of being collapsed by default)
<jugglinmike> Matt_King: And the "About this example" section instead read "About this experimental example"
<jugglinmike> Matt_King: all of these things would change when the example stops being experimental
<jugglinmike> Matt_King: But we won't do this in the pattern itself. It's kind of hidden. Not totally hidden, but kind of
<jugglinmike> Matt_King: My question for the group: Is this design sufficient to make sure people understand that this is experimental?
<jugglinmike> Jem: This is great. I remember talking about this at TPAC. There, I mentioned that I wanted to see a reference to ARIA to help explain why we are experimenting here in APG
<jugglinmike> Jem: I think we're missing that context at the moment
<jugglinmike> Matt_King: We would address that in the "About this example" section by adding a link to the draft
<jugglinmike> Jem: I have some thoughts about the wording of the description
<jugglinmike> Matt_King: I'm still working on the wording; I'm mostly just looking for feedback to the high-level changes (The title, the heading, etc.)
<jugglinmike> Matt_King: At the point in time that it becomes evergreen in ARIA, we would have a pull request that removes the word "experimental" everywhere it shows up, we would remove the metadata that causes it to be listed separately in the index
<jugglinmike> Jem: I like that. I like that we'll be able to prepare for the transition to take place when the time is right
<jugglinmike> jongund: I think it looks good. It seems pretty clear that it's experimental. The word is everywhere
<jugglinmike> jongund: I agree with Jem's feedback to highlight the relationship to the draft spec
<jugglinmike> Bryan_Garaventa: Does it explain what the term "experimental" means?
<jugglinmike> Matt_King: yes
<jugglinmike> Matt_King: I'm going to take this to the next level by updating some of the content. Is that going to be a problem for Alex?
<jugglinmike> howard-e: That should be fine
<jugglinmike> howard-e: Should this be excluded from updating the "coverage and quality" report?
<jugglinmike> Matt_King: I actually think that no, it should not be excluded, for two reasons. I think it would be good to be able to see if the experimental pages cause any quality problems.
<jugglinmike> Matt_King: Second, even if people outside of the APG Task Force look at the report, I think the title of these pages will make it clear to them that these are experimental.

@howard-e do you know why the tests are failing? The failures do not seem related to the changes in the PR. I tried a few retries but that didn't seem to help.

@alflennik you are right that the failure has nothing to do with this PR.

It is the same issue reported in #2938. I haven't spent the time to investigate why it happens but it is being tracked in the APG's issue triaging process process so your work here should be able to continue with that in mind.

@alflennik while reviewing some other PRs, realized I was wrong with my initial statement. It was still a flaky build error but not the issue I originally linked.

I submitted #2996 to reflect the actual failing test that's here and I've also pushed #2997 which should address it.

@mcking65 the supporting build change for this PR has now been merged at https://github.com/w3c/wai-aria-practices/pull/310, so this PR's preview link should now show any experimental content drafted for aria-actions.