Remove Resources and Recommendations Pages in the Accessibility Ready Theme Documentation

[amberhinds]

Issue Description

The Accessibility team would like to condense the Accessibility Ready Theme requirements to be more concise and updated with current standards. As part of our proposed changes, there are two pages that we would remove.

1. Resources page: This page has very little information on it and is not especially useful. We would like to move the few links on this page to a section on the main Accessibility Ready Page instead.
2. Recommendations page: There are two "recommendations" on this page. We feel that recommended but not required criteria are likely to be ignored. We will make Zoomable text a requirement and will delete Removal of title attributes since it is more of a best practice than a true WCAG requirement.

URL of the Page with the Issue

• Resources
• Recommendations

Suggested actions

I can move the resources content onto the main page and then someone can delete and redirect the resources page to the new section on the main page.

For the recommendations page, I would like to delete the content and remove it with an explanation of why there are no longer "recommendations" for the accessibility-ready tag. I would like to leave this up for 90 days before that page is deleted and redirected.

[github-actions[bot]]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[github-actions[bot]]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[justintadlock]

I just realized this was about the Make Themes Handbook and not the Theme Handbook after labeling this. Do we track Make Themes Handbook changes here?

[amberhinds]

I was just going to edit the pages but I think they said I was supposed to post here first. Let me know if I misunderstood.

On Thu, Jul 11, 2024, 6:28 PM Justin Tadlock @.***> wrote:

I just realized this was about the Make Themes Handbook and not the Theme Handbook after labeling this. Do we track Make Themes Handbook changes here?

— Reply to this email directly, view it on GitHub https://github.com/WordPress/Documentation-Issue-Tracker/issues/1634#issuecomment-2224059068, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADELJMCXIXNZ6PWRVHEAVHTZL4BH7AVCNFSM6AAAAABKXULLMSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMRUGA2TSMBWHA . You are receiving this because you authored the thread.Message ID: @.***>

[carolinan]

I think there needs to be a cross team discussion about the goal of the accessibility-ready tag because if the plan is to strictly follow WCAG then that is a change of mindset. I personally do not see why the requirements need to be limited to WCAG if they benefit the theme users.

One of the reasons why the team has asked theme developers to remove title attributes is because they are also being removed from WordPress Core: https://core.trac.wordpress.org/ticket/24766

[amberhinds]

I would be fine it moving the removal of title attributes to a requirement instead of deleting it. At WordCamp yesterday we discussed not wanting to add additional barriers for theme devs and thus it might be better to not add additional requirements beyond WCAG at this point in time.

I agree title attributes create unnecessary noise and we flag them during our accessibility audits. I'm just not sure how strict we want to be with our requirements for the tag.

@joedolson do you have an opinion?

On Thu, Jul 11, 2024, 11:53 PM Carolina Nymark @.***> wrote:

I think there needs to be a cross team discussion about the goal of the accessibility-ready tag because if the plan is to strictly follow WCAG then that is a change of mindset. I personally do not see why the requirements need to be limited to WCAG if they benefit the theme users.

One of the reasons why the team has asked theme developers to remove title attributes is because they are also being removed from WordPress Core: https://core.trac.wordpress.org/ticket/24766

— Reply to this email directly, view it on GitHub https://github.com/WordPress/Documentation-Issue-Tracker/issues/1634#issuecomment-2224399621, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADELJMCZNHCYRD26ZDKFOJTZL5HKTAVCNFSM6AAAAABKXULLMSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMRUGM4TSNRSGE . You are receiving this because you authored the thread.Message ID: @.***>

[carolinan]

I don't think we can assume that it is easier for theme developers, nor reviewers, to read and understand WCAG, than the requirements / recommendation pages. Especially not after the how to guides are updated.

[justintadlock]

Since we have this discussion, I'd like to talk about it in context of the ongoing Theme Handbook overhaul: https://github.com/WordPress/Documentation-Issue-Tracker/issues/816

There's currently the need for someone to write an accessibility chapter with best practices. Ideally, we could consolidate resources and other things here. This is generally useful information for everyone building themes, regardless of where they host those themes. Having this all in one location also means less duplication of work.

Whereas the Make Themes Handbook is best suited for things that are strictly related to people adding their themes to the official Theme Directory.

Resources page: This page has very little information on it and is not especially useful. We would like to move the few links on this page to a section on the main Accessibility Ready Page instead.

This is the part where it would ideally live in the Theme Handbook.

Recommendations page: There are two "recommendations" on this page. We feel that recommended but not required criteria are likely to be ignored. We will make Zoomable text a requirement and will delete Removal of title attributes since it is more of a best practice than a true WCAG requirement.

This needs to be brought up as an agenda item for a theme review meeting, discussed, and voted upon since it's a change of requirements.

[joedolson]

I'd still like people to remove title attributes; it's just a good habit. It is significantly less common as a problem than it was when this project was originally started, but that's largely one of the positive effects of enforcement: long education has had an impact on what developers do by default.

And I definitely wouldn't want to limit these guidelines to just WCAG issues; we can and should have higher standards than that.

The accessibility-ready guidelines also serve as an educational tool for theme developers, to help guide towards better habits in development, and allowing title attributes encourages bad habits by allowing developers to think that text that's only available some of the time to some people is acceptable.

I think that the accessibility team needs to prepare a proposal that can be brought to the themes team for discussion and voting. This shouldn't be particularly controversial; the changes are mostly for modernization and clarity. Some of it is to align with changes in WCAG requirements since the original documents were written and last updated. While we don't want to limit to WCAG, we do need to make sure that we cover WCAG guidelines when we can.

[amberhinds]

@joedolson - I have notes about additional requirements to add to Accessibility Ready requirements. My plan is to create an initial doc for the Accessibility team to discuss and then, at that point, create a different issue as a proposal for the themes team.

I'll include removing the title attributes in that list of requirements.

I'm not sure that should stop us from removing the "recommendations" page as they're not currently required so can't be enforced when testing for accessibility ready in its current state.

[joedolson]

I agree with removing the recommendations page from the theme review guidelines; I don't think it serves a lot of purpose to document things that we aren't actually checking for or requiring. Developers who want to go the extra mile will be able to do that; we don't need to have a document suggesting what they might want to consider.

[carolinan]

I would also like to mention that the intention was always to regularly move requirements from accessibility-ready to the standard theme requirements. It did not happen more than once or twice, and then the team forgot. So it would be great to have a plan for that, too.

[joedolson]

Definitely a good thing to do; but somewhat outside the scope of this document. However, we should make some decision about how to handle the accessibility requirements that are general to all themes. I'm inclined to think that we should still have them listed in the accessibility requirements, but with a flag noting that they are required for all themes.