Harmonize formatting when describing UI elements in docs

[anaxite]

This discussion stems from Talking and Doc'ing a few weeks ago.

The Astro documentation lacks a consistent style rule to format text that refers to a UI label. The team expressed interest in making formatting more consistent and possibly add UI label formatting rules to the style guide. However, we weren't able to agree on what that formatting should be.

This discussion aims to make a decision for UI label formatting.

[anaxite]

Two suggestions came up:

1. Format UI labels by using Markdown bold syntax, such as **text**.
2. Format UI labels by using and HTML elements, as explained on this MDN page.

These two choices could look like this:

Option	Example
Markdown bold	To continue, open the **Tools** menu and select **Inspect**.
kbd/samp elements #1	To continue, open the <kbd><samp>Tools</samp></kbd> menu and select <kbd><samp>Inspect</samp></kbd>.
kbd/samp elements #2	To continue, select the <kbd><kbd><samp>Tools</samp></kbd>⇒<kbd><samp>Inspect</samp></kbd></kbd> option.

My personal preference was option 1, for the following reasons:

• This rule is already the norm in other style guides, such as Microsoft's documentation style guide.
• The rule is simple and easy for contributors to remember.
• Bolded text is rarely used in technical documentation.

Option 2 offers other advantages:

• We could use targeted CSS rules to format the text.
• The semantic nature of the HTML elements could improve accessibility.

Though we didn't discuss other options, there could be a middle ground where the Astro docs add an Astro component to target and style UI labels. It could lead to a version of option 2 that's easier for contributors to implement.

Notes

I would personally like to have real-world data on accessibility. How do screen readers respond to the nested tags? What are the actual benefits?

Other thoughts?

[sarah11918]

Thanks for starting this discussion! It would be good to have some standardization, not the least of which because this would make some great first time contributing opportunities to update existing pages! 🙌

I'll make sure @HiDeoo and @delucis are looped in here because I believe they are familiar with the accessibility implications, and @yanthomasdev might be interested in this conversation as well.

[sarah11918]

As for thoughts on the choices:

• the first one is the clear winner from an authoring standpoint.
• we don't have that many occurrences of this, since documenting Astro itself doesn't really involve much documenting of using UI elements (it's mostly our 3rd-party guides), so I'm not entirely opposed to the second choice (as clunky as it may be to write) if we believe there are really compelling reasons to choose it. But, it certainly is going to have to prove itself, with that kind of notation required!

[delucis]

I guess if we did want the more complex syntax, we’d likely abstract it into a component, something like:

<UI path={['Tools', 'Inspect']} />

But I agree in principle that the bolding approach is a simpler thing to author. And I agree with @anaxite that we should evaluate just how much (if at all) the more complex syntax would improve things.

[delucis]

In a quick test in Firefox and Edge, the <kbd> and <samp> elements in the example in the MDN docs didn’t seem to have any additional semantic impact. In the accessibility tree these were just present as regular text leaf nodes and macOS Voice Over read them as inline text.

I think @HiDeoo maybe mentioned that these do have an impact in some contexts (with specific devices/screen readers), so might need him to confirm this.

[HiDeoo]

Indeed, in most contexts, <kbd> and <samp> do not provide additional commands, interaction, special semantics, or unique aural distinctions when used in HTML documents as it can be seen in the following reports:

• JAWS
• NVDA
• VoiceOver macOS
• VoiceOver iOS
• TalkBack

Altho, Chris is correct, I was definitely remembering having notes about a potential use case I encountered in the past. After some digging, I found them and it's related to Dolphin ScreenReader which had special handling for them in their item finder, altho I no longer have a complete license to test it as this was a long time ago (and this was pretty limited anw).

Considering all this, if the visual styling desired is just bold text, then we should be more than fine using basic Markdown (and we can always re-visit if we get some reports about it or things evolve in the future). If we need more advanced styling, we may as well use the dedicated HTML elements so we can easily target them with CSS (through the use of a component to simplify the syntax as Chris suggested).

Though we didn't discuss other options, there could be a middle ground where the Astro docs add an Astro component to target and style UI labels. It could lead to a version of option 2 that's easier for contributors to implement.

I guess having a dedicated component, even if it ends being just bold, could make it easier to document and potentially enforce some kind of consistency in the future, it's a bit more memorable than using raw Markdown I guess.

I'd also add that this is only true in the context of UI labels (and not keyboard shortcuts which can be a totally different story).

[bjohansebas]

my two cents, i like keeping things simple, even if that means making a trade-off with accessibility. Having a dedicated component doesn’t sound bad either, and I actually like the idea quite a bit, but I really prefer option one of using Markdown bold.

[sarah11918]

Alright, so I think the consensus here is that we're probably happy enough with bold Markdown for the cases where this occurs! This means we don't have to explain custom elements to contributors, and we don't have to go through and update older pages.

I think if we were regularly documenting UI then this might be something we consider worth the additional effort and friction, but I don't think our current use of bold has hurt anyone's comprehension in the few places it's used throughout our docs.

[anaxite]

Sounds good! I'll start having a look at the documentation (and style guide).