docs: use <h4> instead of <h1> for <aside> notes

[orangecms]

coming from #5453

There should only be a single highest-level headline, see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements#avoid_using_multiple_h1_elements_on_one_page

Regarding aside, https://kb.daisy.org/publishing/docs/html/asides.html

the first heading level within an aside should always be
one level lower than its containing section.

If a publisher cannot maintain heading numbering consistency, they
should try to find another method that users can predict.
For example, using h6 for all sidebars.

Most pages have second- and third-level headings, so use fourth level headings to keep it simple.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: orangecms
Once this PR has been reviewed and has the lgtm label, please assign varshaprasad96 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

Hi @orangecms. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[camilamacedo86]

Hi @orangecms

thank you for your contribution 🎉

I am trying to identify here : https://deploy-preview-5457--kubebuilder.netlify.app/quick-start.html
What changed for the end user?
Could you please help me out?

Can you please add in the description before the change a note was render as :

Now, with the change we can see that ...

[orangecms]

The change is the semantics. You cannot "see" it, as it appears to people using screen readers, see the references I added in the commit message.

[orangecms]

Looking further, aside is maybe not the right choice after all...
https://html.spec.whatwg.org/multipage/sections.html#the-aside-element
there is a note on that very page, and they use a simple <p>, which makes sense since the note is really part of the content, not tangential.

[camilamacedo86]

The change is the semantics. You cannot "see" it, as it appears to people using screen readers, see the references I added in the commit message.

Could you walk me through the steps of how this will generate a different diff?
Is it based on viewing/comparing the file as Markdown? If that doesn’t change the output, I’m a bit unsure what the practical benefit is.
Could you clarify what value this adds? If there’s no tangible impact, I’m wondering whether it’s worth the effort to implement and enforce.
In other words: What value does this bring in practice? If the impact is minimal or none, why should we spend effort implementing it and trying to enforce it?

[orangecms]

The change is the semantics. You cannot "see" it, as it appears to people using screen readers, see the references I added in the commit message.

Could you walk me through the steps of how this will generate a different diff?

I'm not sure what you mean by "different diff", could you elaborate?

Is it based on viewing/comparing the file as Markdown? If that doesn’t change the output, I’m a bit unsure what the practical benefit is.

This is a semantic change and benefits people using assistive technology such as screen readers.

Could you clarify what value this adds? If there’s no tangible impact, I’m wondering whether it’s worth the effort to implement and enforce.

This adds the clarity that the info boxes contain extra information and do not contain the most important headings.

In other words: What value does this bring in practice? If the impact is minimal or none, why should we spend effort implementing it and trying to enforce it?

In practice, again, this is a semantic improvement.
The effort was as simple as sed -i 's/<h1>/<h4>'. Took a few minutes.

Nothing needs enforcing.
So far, there is no mention of those aside-boxes in the CONTRIBUTING.md. As we discussed earlier, I would file a PR to add it there. I wanted to get aligned on the correct way of doing that first.

[vitorfloriano]

Can you please add in the description before the change a note was render as :

I understand that this change is mostly about semantics and accessibility.

For example, if the user relies on a screen-reader tool, the wrong heading levels can mess up the sequence in which elements are read.

There should not be any visual changes for most users, and that's good.

THAT being said, I think applying a header number to all elements (be it h1 or h4) is not a very good approach because each page has its own levels.

@orangecms I ran the accessibility checks on Chrome devtools and got this:

So, I understand that the problem is creating a custom box element mixing aside with header levels. It doesn't matter what level we pick, it will always end up with a11y issues.

That's why I think we should strive to use Markdown as much as possible, using HTML only if mdBook does not provide a render for what we want to achieve.

[orangecms]

So, I understand that the problem is creating a custom box element mixing aside with header levels. It doesn't matter what level we pick, it will always end up with a11y issues.

Agreed, it's not ideal, just slightly better, as DAISY also writes as a recommendation; see my commit message citing it.

That's why I think we should strive to use Markdown as much as possible, using HTML only if mdBook does not provide a render for what we want to achieve.

I would agree that using Markdown should be preferred, but rather because the tooling (such as mdBook) would then be leveraged, even though this is extended/somewhat custom Markdown. Just mixing lots of HTML into it feels strange to me.

Regarding semantics again, the Markdown info boxes, I just checked, are currently rendered as <blockquote> elements, which is also questionable, per https://html.spec.whatwg.org/multipage/grouping-content.html#the-blockquote-element :

The blockquote element represents a section that is quoted from another source.

The problem overall is that HTML does not have semantic elements for everything, such as in this case.
WHATWG themselves render their note boxes using <p class="note">.
That is, it carries no semantics (sadly), only visually shows what it's about.

I really didn't mean to start any bikeshedding here, sorry. :3

[orangecms]

Addendum: The way to go now after some more searching appears to be the role="note" attribute. So I suggest sticking with the <aside> for now and switching to <p> and adding the role in another PR. WDYT? :)

[orangecms]

I've filed a PR against mdBook, and even deeper in the rabbit hole 🐰 🕳️ , filed an issue against pulldown-cmark, and on and on... 😅

[vitorfloriano]

So I suggest sticking with the <aside> for now and switching to <p> and adding the role in another PR. WDYT? :)

I think we could go incrementally about this.

Changing 40+ files makes it much harder to review, even though the change is literally the same. What about experimenting with only one page of the book, like a PoC? Then we can easily check how it looks, how it performs in the a11y side of things, perhaps collect some a11y benchmarks, then iterate on other pages.

I've filed a PR against mdBook, and even deeper in the rabbit hole 🐰 🕳️ , filed an issue against pulldown-cmark, and on and on... 😅

Wake up, Neo... Jokes aside, in the end, I honestly think the best way to go about this is to solve it in the upstream. mdBook is great but needs a lot of improvements on the a11y front, from contrast to navigation, ARIA, etc, lots of improvements to be done there. Those are easier to contribute to because the templates are in pure HTML & CSS, no Rust needed. Even I managed to a get a PR merged there.

[orangecms]

Heh, I'm good with both Rust and the web side, having worked on web apps for a decade and comng from a systems and security background. I use kube.rs these days at work, which is how I came here. =)

Now we still need a bit of alignment. IIUC, you and I both would prefer migrating to the Markdown notation, which would mean that we leave a11y concerns to upstream (my PR against mdBook would just do that) and otherwise, it's a visual change, but also dropping the extra note headline.

From what I see, those headlines are mostly redundant anyway, so that should be okay; we could highlight keywords in bold if necessary.

For such a big change, sure, file by file would be the way to go, unless I wanted to write a little parser for a migration tool.

[vitorfloriano]

Now we still need a bit of alignment. IIUC, you and I both would prefer migrating to the Markdown notation, which would mean that we leave a11y concerns to upstream (my PR against mdBook would just do that) and otherwise, it's a visual change, but also dropping the extra note headline.

Yeah, I would much rather stick with Markdown only, but that could be too disruptive, I think. For example, the Quick Start page seems to have more lines inside <aside> boxes than outside them. 😅

https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/quick-start.md?plain=1

If you have any ideas on how to better format this page, one that brings value to readers and which doesn't feature inline HTML, than I think that could be a good candidate for a PR.

Most of the changes in the book were driven by user feedback. See: #4862

For me, personally, it's hard to gauge if a page is good or not because I don't have an "eye" for it and sometimes I'm clueless about reading UX/UI, but hopefully there are devtools and guidelines (and folks like you) to help.

[camilamacedo86]

Thanks for working on this! 🙏

I saw the accessibility warning in Chrome DevTools about heading order not being sequential.

Before we change the docs structure, could you help with concrete user scenarios where this actually affects people?

For example:

• What real problem do end users have today because of this?
• Which users are impacted (screen reader users, keyboard navigation, TOC, etc.), and how?
  - What is something that is not possible (or significantly harder) if we don’t fix this?

IHMO: We should not really care about warnings shown in Chrome DevTools by themselves.

What we should care about is having clear, nice documentation that helps end users quickly find the information they are looking for — especially for specific use cases.

Right now, our callout boxes and their headers work as a filter:
“Only read this if this applies to you.”
We have many caveats and notes that only matter in specific scenarios, and this structure helps users scan the page without needing to read everything.

I’m concerned the proposed change makes these callouts harder to scan and results in a worse UX for most readers:
#5459

Also, we don’t have the bandwidth to open many PRs and review all of them carefully to make sure nothing breaks or that the docs still feel good for end users after the changes — unless this clearly solves a real user problem.

So for me, the key question is:
What user problem does this fix, and why is it worth the UX trade-off?

/hold until we have more clarity in what is the problem that we are trying to solve and for who to ensure that we have a clear benefit within the changes

[orangecms]

Before we change the docs structure, could you help with concrete user scenarios where this actually affects people?

For example:

• What real problem do end users have today because of this?
• Which users are impacted (screen reader users, keyboard navigation, TOC, etc.), and how?
  - What is something that is not possible (or significantly harder) if we don’t fix this?

To people using assistive tooling, the hints/notes currently look like they are the main content of the page.
It's as if it were in a very large font size.
At the same time, the <aside> tag suggests that the content is only tangentially related to the rest of the page, like an ad.
That makes it hard for them to understand that it's meant to be a note and rather ancillary. That's what role="note" is for.

Right now, our callout boxes and their headers work as a filter: “Only read this if this applies to you.” We have many caveats and notes that only matter in specific scenarios, and this structure helps users scan the page without needing to read everything.

I’m concerned the proposed change makes these callouts harder to scan and results in a worse UX for most readers: #5459

Tips/notes suggest the same thing, and with the highlights in bold, it's apparent what the respective note is about.
How relevant the respective information is, and this is relevant for assistive tooling again, is determined by the kind of admonition, e.g., a warning or caution would be more relevant for skimming than a tip. People with a screen reader could skip ahead if they didn't want to read a tip/note.

Also, we don’t have the bandwidth to open many PRs and review all of them carefully to make sure nothing breaks or that the docs still feel good for end users after the changes — unless this clearly solves a real user problem.

So for me, the key question is: What user problem does this fix, and why is it worth the UX trade-off?

This specific PR means no visual change and otherwise just a slight improvement wrt structure, albeit not perfect.

/hold until we have more clarity in what is the problem that we are trying to solve and for who to ensure that we have a clear benefit within the changes

I had changed it back to draft for now. since there were open discussions and @vitorfloriano and I would prefer admonitions and hence the other PR.

Thanks.

[camilamacedo86]

Hi @orangecms,

Thanks for trying to clarify this for me.

If these warnings make the experience harder for users or cause a real accessibility issue, then yes—we should look into whether we can improve it.

It would be great to test this with an accessibility tool, capture what problem the user actually faces, and then open an issue. That way we can track the specific problem we want to solve.

See:

Tips/notes suggest the same thing, and with the highlights in bold, it's apparent what the respective note is about.
How relevant the respective information is, and this is relevant for assistive tooling again, is determined by the kind of admonition, e.g., a warning or caution would be more relevant for skimming than a tip. People with a screen reader could skip ahead if they didn't want to read a tip/note.

That is not true.
In our case we have many caveats.
Example: It only matters if you are using the Master branch, it only matters if you want to have autocomplete. See; #5459 (review)

We also have caveats like, it only matters if you are using an external type, so the reader skip the content.
Therefore, Only TIP, Warning does not solve this need by itself. :-(

So, if you want to propose a change to fix this issue, we’ll need to make sure the solution doesn’t force end users to read everything just to figure out whether it’s relevant—and that we still maintain a good user experience. For example, can we use TIP, Warning with the subtitles ? Could we solve the H1--H4 with class and js?

[orangecms]

Hi @orangecms,

Thanks for trying to clarify this for me.

If these warnings make the experience harder for users or cause a real accessibility issue, then yes—we should look into whether we can improve it.

It would be great to test this with an accessibility tool, capture what problem the user actually faces, and then open an issue. That way we can track the specific problem we want to solve.

I had already created #5453 to track the discussion. Let's reopen it.

See:

Tips/notes suggest the same thing, and with the highlights in bold, it's apparent what the respective note is about.
How relevant the respective information is, and this is relevant for assistive tooling again, is determined by the kind of admonition, e.g., a warning or caution would be more relevant for skimming than a tip. People with a screen reader could skip ahead if they didn't want to read a tip/note.

That is not true.
In our case we have many caveats.
Example: It only matters if you are using the Master branch, it only matters if you want to have autocomplete. See; #5459 (review)

We also have caveats like, it only matters if you are using an external type, so the reader skip the content.
Therefore, Only TIP, Warning does not solve this need by itself. :-(

I feel like this discussion will not resolve anytime soon. I'll try one last time and then give up.
Currently, there is no hint for assistive tooling, and with my proposed changed that has highlights in bold, the relevance is still clear to non-impaired readers.

So, if you want to propose a change to fix this issue, we’ll need to make sure the solution doesn’t force end users to read everything just to figure out whether it’s relevant—and that we still maintain a good user experience. For example, can we use TIP, Warning with the subtitles ? Could we solve the H1--H4 with class and js?

No. Classes are not for semantics and structure, they are for styling. Neither is JS, that is for interactive bits. I mean, we coule rewrite the h1 into h4 via JS, but then we could just have that in the static content already.

The next suggestion would be to change the <aside>s into <div role="note"> on top of changing the heading levels.

[vitorfloriano]

The next suggestion would be to change the <aside>s into <div role="note"> on top of changing the heading levels.

1+ for swapping <aside><h...> for <div role="note"><p>(or whatever else but a header tag to avoid messing with hierarchy) and try as much as possible to not change the style (keep the scope within a11y and semantics) so all possible readers are happy.

That may be the best compromise.

We may eventually switch to admonitions to keep it Markdown-only when mdBook supports custom admonitions and pulldown-cmark fixes the semantics for them.

WDYT?