fix(svg attributes): Remove the element list and reorder sections (for attributes u-z )

[dipikabh]

Description

I came across the SVG x attribute page while triaging #32081.

The element list under "You can use this attribute with the following SVG elements:" resembles a Table of Contents (TOC) but it is not. I found this list alongside the "In this article" sidebar links confusing.

The links in the element list take you to the respective element pages whereas I was expecting navigation to sections on the attribute page itself.

Given that the sidebar is meant for in-page navigation, and each element section already includes a link to its corresponding element page, the initial list of links appears to be redundant.

This PR:

• Removes the element list from attribute pages that contain subsequent sections for those elements. Each section contains a link to the corresponding element page, so that navigation aid is not lost.

• Renames "Example" to "Examples". This aligns with our use of the plural form for this section. For example, in the SVG element page template, the guideline is: "Note that we use the plural "Examples" even if the page only contains one example."

• Changes the position of the "Examples" section so that it follows "Usage notes" or appears before "Specifications" (as in SVG element page template and various other templates).
  (The appearance of examples before an explanation of the values was reported as a problem in SVG preserveAspectRatio documentation flow/ordering is confusing #31825.)

• Uses the section name "Usage notes" when a description of values is included and the name "Usage context" when the section contains only a table. The section name "Context notes" appears only on SVG attribute pages; it has been updated to "Usage notes" or "Usage context" as appropriate.

Note: The improvements in this PR focus on attributes with names starting from U to Z.

Motivation

To help streamline navigation and improve consistency with other parts of MDN

[github-actions]

Preview URLs (21 pages)

• /en-US/docs/Web/SVG/Attribute/u1
• /en-US/docs/Web/SVG/Attribute/u2
• /en-US/docs/Web/SVG/Attribute/unicode-bidi
• /en-US/docs/Web/SVG/Attribute/unicode
• /en-US/docs/Web/SVG/Attribute/vector-effect
• /en-US/docs/Web/SVG/Attribute/viewBox
• /en-US/docs/Web/SVG/Attribute/visibility
• /en-US/docs/Web/SVG/Attribute/width
• /en-US/docs/Web/SVG/Attribute/word-spacing
• /en-US/docs/Web/SVG/Attribute/x1
• /en-US/docs/Web/SVG/Attribute/x2
• /en-US/docs/Web/SVG/Attribute/xChannelSelector
• /en-US/docs/Web/SVG/Attribute/x
• /en-US/docs/Web/SVG/Attribute/xlink:title
• /en-US/docs/Web/SVG/Attribute/xml:lang
• /en-US/docs/Web/SVG/Attribute/xml:space
• /en-US/docs/Web/SVG/Attribute/y1
• /en-US/docs/Web/SVG/Attribute/y2
• /en-US/docs/Web/SVG/Attribute/yChannelSelector
• /en-US/docs/Web/SVG/Attribute/y
• /en-US/docs/Web/SVG/Attribute/z

(comment last updated: 2024-04-19 15:25:21)

[estelle]

I made a few suggestions to improve the docs as long as we're in her editing them.

[dipikabh]

Hi @estelle, thanks a lot for reviewing these pages!

I've accepted your content additions/improvements (thank you for the suggestions). I believe we can address these concerns in a separate issue/PR. The focus of the current set is to fix the navigation and ordering of sections.

Please see my response in #32965 (comment) for the reasoning behind some of the changes. You can preview them on the viewBox page. If these changes look okay to you, I'll replicate them to other pages. Thanks!

[hamishwillee]

I've removed my review request as it looks like @estelle has sorted this. You can add me back if further review is needed.

[estelle]

The focus of the current set is to fix the navigation and ordering of sections.

I am not a fan of the h2s as the reader doesn't know if "use" is an element or another section of the page; the elements aren't differentiated from the other page sections. As it's currently like that, and this doesn't address it but doesn't make it worse, no reason to hold up a PR (though opening an issue would be great so we can remember to address this in the future)

hmmmmm, should we solve this by adding < and > to the h2 elements?

[dipikabh]

I am not a fan of the h2s as the reader doesn't know if "use" is an element or another section of the page.

Correct and I agree. I think we're saying the same thing :) Just to be sure:

Current viewBox:

What I'm proposing (viewBox preview):

I am guessing that the only point where we differ is whether or not to have a hand-curated TOC to various element sub-sections. That is, I am not in favor of including this linked list:

[dipikabh]

Hi @estelle, I've updated the files to remove the elements as H2s and also added code styling to element headers in 110ef88.

As a sample, you can check the width attribute page: https://pr32965.content.dev.mdn.mozit.cloud/en-US/docs/Web/SVG/Attribute/width .

I hope this is looking good to land. Thanks for your review!

[estelle]

Some of the examples were duplicates, so made suggestions to create different yet useful ones.

[dipikabh]

Thanks for the suggestions, @estelle! I've applied them as is.

It might be better to address the content concerns and updates in a separate PR. This one was specifically aimed at fixing only the navigation, and I was waiting to get this approved before making similar changes to other attribute pages. I hope we can land this soon. In similar subsequent PRs, I'll happy to take up content improvements separately.

[dipikabh]

Thanks, @estelle 🎉