Document nuance around `no-duplicate-header` rule

[khiga8]

This rule is set to true but I think there's some nuance around when this rule should be configured.

The rationale behind the no-duplicate-header rule is that some markdown parsers will generate anchor links from headings, and if the heading is the same, two headings in separate areas of the page will share the same anchor link. We see this issue in Primer docs.

However, on GitHub repos, the GitHub markdown parser ensures headings that share same text have unique IDs so the generated anchor links are unique even if the heading text is the same.

So I believe we wouldn't need to enforce that heading texts on a page are completely non-duplicated in other cases. I don't believe it's necessary to have completely unique heading text on a page for accessibility purposes. However, I believe there are accessibility benefits from enforcing that sibling headings are unique.

We could recommend setting siblings_only parameter which allows heading duplication for non-sibling headings and enforces sibling headings are unique.

Could we document these nuances?

[rachmari]

@khiga8 I'm curious if you've come to a decision on the accessibility of duplicate Markdown headers, when the slug is unique. We're considering adding a custom rule to catch duplicate headings on docs.githhub.com, and I'm curious if it is necessary.

cc @lecoursen (docs accessibility lead)

[khiga8]

Hey @rachmari, thanks for reaching out!

In the following example, the duplication of Features is acceptable because the parent heading text is unique.

(Staff-only: Related slack thread)

# Change log

## 1.0.0

### Features

## 2.0.0

### Features

However, having multiple duplicated levels under the same parent can make navigation confusing for all users and is discouraged:

# My Pull Request

## Changes made

## Reasons

## Changes made

## Reasons

Making sure we have unique slugs will ensure that an anchor link navigates to the section that a user expects 👍. However, I think this addresses a slightly different concern from having a helpful heading structure, and there's benefit in making sure headings aren't duplicated at the same level.

The native no-duplicate-heading rule offers a siblings_only option to flag only the latter scenario which could be worth checking out.

[rachmari]

@khiga8 thank you for the detailed explanation. 🙏 We definitely want to make sure that there are no sibling heading levels that are duplicated.

I'm curious what the guidance for meeting MAS-C. Awhile back, to conform to MAS-C, we added some more verbose headings to some automated documentation.

For example on this page, you'll see a heading for an API operation and within that section there are subheadings. It was concluded that to maintain MAS-C, each heading had to be unique. So sub-headings like "Parameters" was changes to "Parameters for " and "Fine-grained access tokens" to "Fine-grained access tokens for ."

I was always curious why this was necessary or if it actually was, but wasn't directly involved with the MAS-C work. If the subheadings have unique slugs do they need to be unique on the page when the parent heading is indeed unique (in terms of meeting MAS-C)?

[lecoursen]

For context, our "no duplicate headers" rule came out of https://github.com/github/docs-strategy/issues/1594. It discusses 3 audit issues but looks like only these two mention duplicate headers:

• https://github.com/github/accessibility-audits/issues/858
• https://github.com/github/accessibility-audits/issues/839

The first is most directly relevant:

Finally, there are two headings present with the same text of “Guides”, making it difficult for screen readers to distinguish between the meaning/content of sections with the same title.

[khiga8]

Hey @lecoursen, feel free to follow along on this slack thread!

[patrickhlauke]

Agree with @khiga8 that there's a bit of nuance involved. WCAG 2.4.6 Headings and Labels does require a bit of interpretation/judgement, as there's a sliding scale of "how descriptive/appropriate is the heading?"

For sibling headings (at the same heading level, and falling under the same parent heading), I agree that it's a strong "code smell" if they have the exact same text - that almost certainly points to a situation that likely fails 2.4.6 outright.

<h1>…</h1>
<h2>Something</h2>
…
<h2>Something</h2>
…

However, there will be cases where headings have the same text, but fall under different parent headings, and thus make sense. Those are likely not failures of 2.4.6.

<h1>Recipes</h1>
<h2>Pizza</h2>
<h3>Ingredients</h3>
…
<h2>Lasagne</h2>
<h3>Ingredients</h3>
…