Link to related rules in the background

[WilcoFiers]

This came up recently in the ACT TF. Some rules are closely related to others. Especially if rules are about the same type of element and the same type of requirement, it would be good to link between them.

For example, these three rules should probably all link to each other:

• HTML page has lang attribute
• HTML page lang attribute has valid language tag
• HTML page lang and xml:lang attributes have matching values

That also serves as an example of something that I think should not be linked. "Element with lang attribute has valid language tag" is about a different element and a different SC, so even though they are "related" I don't think we should link to that.

Opening this as an issue so that we can discuss before we start to do this.

[Jym77]

I like it.
It would help to understand that each of these rules is a very partial one and part of a larger test.

We're pushing a lot into Background these days. We might want to start structuring it (e.g. subsections "Related rule", "Documentation/Specification", "Notes", …)

[EmmaJP]

Perhaps some kind of automated "related content" based on metadata in the rule files?

[WilcoFiers]

I've thought about this some more. I see the value of having some kind of metadata referencing related rules. The issue is that I think this information does best fit in the background, and "magically" injecting information in the background, while possible, isn't ideal. It can be confusing where that information comes from.

The biggest benefit I see to generating this off metadata is that it is easier to keep the information up to date. However, this is not something that changes all that often. I'm not convinced the overhead of building something is worth (in my opinion) fairly minor benefit of not having to update these links manually.

[EmmaJP]

I think this could be more about making the ACT Rules website a little more usable. Especially if you think of this a bit like tagging up editorial content with keywords so that users can filter similar content.

I don't think that would fit with the Background of a rule. Possibly the Useful Links part of a rule, or a nested related rules list within it.

Here's my thinking on it ... In a rule file there could be an additional key-pair in the initial metadata stuff. It could even be 'keywords' that then connects a rule with other rules that have a matching keyword. This would reduce the need to know what those other rules actually are. For example:

acknowledgments:
  authors:
    - 
keywords:
  - aria
  - role
  - relationships
---

In the rule's website page, the Useful Links would then include links to the rules that match at least one keyword. For example:

Useful Links

• Github issues related to this rule
• Changelog
• Propose a change to the rule
• Test case file for use in the WCAG-EM Report Tool
• Other rules that may be of interest:
  • Rule that is also about aria
  • Rule that is also about relationships

[WilcoFiers]

Some more thought, in prep for this conversation on Thursday. I like that suggestion, I think that is something we should look into, but I don't think it solves the more immediate issue. The reason this issue was opened was because a fairly common piece of feedback to rules is that it's not clear if something very closely related to this rule is tested in another rule. See my example of the three page language rules. Someone sees one of those and immediately wonders if the reason the rule is scoped the way it is, is because there is another rule that addressed the other part of that requirement.

[WilcoFiers]

Decided on the call to do the keywords suggestion separate from adding links to the background. Keeping rules that are designed to fit together up to date with each other should not be too challenging.