Organising background citations

[Jym77]

The background section of some rule has a lot of links to other documents that are just thrown in without much order, mixing in links to related rules, WCAG, technical specifications, related readings, … It can sometimes get hard to make sense out of it.

Notably, we've recently added links to related rules to alleviate some questions around "why does the rule only look at this?" but, for example in https://act-rules.github.io/rules/b5c3f8#background I feel it's hard to figure out that the first two links are related rules while the other are WCAG or technical specification. (at least, there is no visual cue that there is any semantic difference between these links).

In #1528, I tried to use nested list. Maybe not to a very good result…
Some ways to organise links could be:

---

Keep as is

• HTML page lang attribute has valid language tag
• HTML page language subtag matches default language
• Understanding Success Criterion 3.1.1: Language of Page
• H57: Using language attributes on the html element
• BCP 47: Tags for Identifying Languages
• The lang and xml:lang attributes

---

Nested lists

• Related rules:
  • HTML page lang attribute has valid language tag
  • HTML page language subtag matches default language
• WCAG resources:
  • Understanding Success Criterion 3.1.1: Language of Page
  • H57: Using language attributes on the html element
• Technical specifications:
  • BCP 47: Tags for Identifying Languages
  • The lang and xml:lang attributes

Problem: might end up weird when some of the nested lists have only one element.

---

Tagging links

• ACT rule: HTML page lang attribute has valid language tag
• ACT rule: HTML page language subtag matches default language
• WCAG: Understanding Success Criterion 3.1.1: Language of Page
• WCAG: H57: Using language attributes on the html element
• Technical: BCP 47: Tags for Identifying Languages
• Technical: The lang and xml:lang attributes

or

• ACT rule: HTML page lang attribute has valid language tag
• ACT rule: HTML page language subtag matches default language
• WCAG: Understanding Success Criterion 3.1.1: Language of Page
• WCAG: H57: Using language attributes on the html element
• Technical: BCP 47: Tags for Identifying Languages
• Technical: The lang and xml:lang attributes

Problem: might hamper readability by repeating the tags (especially in long lists).

---

Subheadings

Background

Bibliography

Related rules

• HTML page lang attribute has valid language tag
• HTML page language subtag matches default language

WCAG resources

• Understanding Success Criterion 3.1.1: Language of Page
• H57: Using language attributes on the html element

Technical specifications

• BCP 47: Tags for Identifying Languages
• The lang and xml:lang attributes

Problem: ends up with a lot of subheadings in a section that doesn't have any other…

---

Other?

---

All these obviously need some sort of agreement on the broad categories used, but that can also come a bit later with a bit more feedback on what is done.

[EmmaJP]

Suggest a halfway between the headings (semantic support for AT users) and link context. Something similar to this...

Background

Bibliography

• WCAG: Understanding Success Criterion 3.1.1: Language of Page
• WCAG: H57: Using language attributes on the html element
• Technical specification: BCP 47: Tags for Identifying Languages
• Technical specification: The lang and xml:lang attributes

Related rules

• HTML page lang attribute has valid language tag
• HTML page language subtag matches default language

[WilcoFiers]

Discussed this in the TF today. They suggest flipping the order of the headings around (Related rules first), and then use "Other resources" instead of "Bibliography".

[HelenBurge]

If there are no related rules - do I add the heading "Related rules" and have no content afterwards or just add N/A? Or leave the content as it is?

This is shown in https://act-rules.github.io/rules/5f99a7

I will update the others with both lists.

[carlosapaduarte]

I would remove the heading "Related rules" when there are none

[HelenBurge]

But add "Bibliography" to the list of links per rule?

[carlosapaduarte]

I think so. We should keep that heading.