Should descriptions for similar theme share the same pattern?

[akaabdullahmateen]

Consider this example from the <audio> element's Usage notes. There are three sub-headings: HTMLMediaElement.audioTrack, HTMLMediaElement.videoTrack, and HTMLMediaElement.textTrack. All three are extremely similar in nature except for the replaced use of the words audio/video/text as appropriate. Yet, all three of them are worded very differently. For the exact same usage, they use the verbs: alerted, informed, and notified, respectively; which just adds confusion, ambiguity and distinction when there should be none.

For comparison, here is what alternative versions would look like:

• HTMLMediaElement.audioTrack: An audioTrackList containing all of the media element's audio tracks. You can add an event listener for addtrack to this object to be alerted when new audio tracks are added to the element.
• HTMLMediaElement.videoTrack: A videoTrackList containing all of the media element's video tracks. You can add an event listener for addtrack to this object to be alerted when new video tracks are added to the element.
• HTMLMediaElement.textTrack: A textTrackList containing all of the media element's text tracks. You can add an event listener for addtrack to this object to be alerted when new text tracks are added to the element.

This distinct wording and varying descriptions for very similar topics is observed across different articles and HTML element references, for example, as well. Consider the descriptions of the attribute crossorigin under the <video> element, <audio> element, and <img> element. All three of them should have the same exact description except for the replaced usage of the words video/audio/image as appropriate.

If more detail is present for an attribute under one element, it should be visible (either copy-pasted or hyperlinked) for the same attribute under a different element. Because, as it currently is, some elements have important details for an attribute, that is not visible under another element for the exact same attribute when there use is intrinsically same. For example, consider these examples:

• <a> download attribute and <area> download attribute : This is correct because the same details for the attribute download is visible (through hyperlink) under both elements.
• <a> href attribute and <area> href attribute : There are different details under both elements for the same attribute in same context.
• <a> rel attribute and <area> rel attribute : There are different details under both elements for the same attribute in same context.

[schalkneethling]

Tagging @mdn/yari-content ☝️

[dipikabh]

Hello @akaabdullahmateen, thanks for taking the time for bringing this issue to our attention as well as for suggesting the solution.

You are correct - the descriptions in the cases you've highlighted can be made similar/consistent. Same for the attribute description. A link to the attribute with more/different details would be nice.

Before we implement a fix, we wanted to check with you if you would like to open a PR yourself. You can reference this discussion if you decide to open the PR.

[akaabdullahmateen]

Yes, I would love to open quite a few pull requests myself. And thanks a lot @dipikabh for this opportunity!

There is a small catch however, I am still a university student and do not have much experience with open source. However, I have read the contribution guidelines. This is how my workflow looks like right now:

1. I have a local clone of content, which has an additional remote other than origin, named: upstream - which is the official mdn/content. I frequently fetch and merge updates from upstream, so it is in sync most of the time.
2. I have created a new branch: akaabdullahmateen (my own username, so it could be unique).
3. I am reading the entire HTML, CSS, and JavaScript references, for personal interests. These are the two main things I want to improve:
   • Spelling and grammar mistakes.
   • Consistency mistakes.
4. I will edit and commit changes separately to this branch, and every once in a while I will create pull requests from this branch.
5. If the first few PRs get accepted without much objections, that will give me the motivation to continue.

[bsmth]

That sounds great, thanks for your interest in contributing. Feel free to open a pull request when you are ready, keeping in mind to group changes together when it makes sense so that PRs are not too big to review or not too small that you have to open multiple minor ones.

The guidelines are a great place to start, like you mention and don't hesitate to ask here in this discussion if you need help. 🙌🏻

[jpmedley]

We do try to do that. Please understand that it's a bit of a game of whack a mole on a site where anyone can contribute.

[akaabdullahmateen]

I would appreciate any feedback on my pull request #21749. Its been nearly a week 😭
@jpmedley @schalkneethling @dipikabh @bsmth

[Rumyra]

Apologies @akaabdullahmateen and thanks for the pull request! If you've finished working on it could you un-draft it so we can review and merge - thank you!

[akaabdullahmateen]

@Rumyra Mr. Joe Medley already reviewed it, and it was my mistake that I drafted it. I re-opened the pull request, so you can review and merge it whenever you please. Thanks for all the help and assistance.