Project: HTML best practices

[estelle]

All HTML examples should follow best practices.

Media

• All images should include an alt attribute
  • Create spreadsheet of missing alt attributes
• All images should aslo include a height and width (newer best practice)
• All audio files should have a transcript, captions, and description
• All video files should have a transcript
• Video and audio should have autoplay=off (not sure this is necessary anymore)

Form elements

• No form control should exist without an associated label

  • checkbox
  • radio
  • hidden
  • text
  • password
  • tel
  • number
  • color
  • range
  • date/time
  • select
  • textarea

• Every form control should have an id (except in the rare case where implicit labels are used)

  • checkbox
  • radio
  • text
  • password
  • tel
  • number
  • color
  • range
  • date/time
  • select
  • textarea

• All input elements should include a name (and value if needed)

  • checkbox (value recommended)
  • radio (value required)
  • hidden (value required)
  • text
  • password
  • tel
  • number
  • color
  • range
  • date/time
  • select
  • textarea

• All checkboxes, radio buttons, and hidden input types should also include a value

  • checkboxes and radio buttons should be inside <fieldset>s
  • [ ]

• HTML docs should be standards compliant

  • doctype
  • html element should include a lang attribute.
  • charset
  • title
  • viewport meta

• Type attribute is NOT needed

  • script
  • stylesheet

Required attributes, elements, and content

• Ensure abbr has a title attribute unless the abbreviation is preceded or followed by the definition.
• Ensure all links have adequate content ("click here" is a no-no).
• Every <table> should have a table <caption>
  • in code examples
  • in markdown (how is this done?)

Deprecated content

• Most occurrences of i and b should be converted to em or strong, depending on the context #139
• Ensure acronym is no longer used.
• Figure out if hgroup is back. If no, remove it from all but the essential occurrences

[Seirdy]

Figure out if hgroup is back. If no, remove it from all but the essential occurrences

hgroup does seem to be back; a change to the HTML Living Standard now clarifies that it can define a subtitle.

See whatwg/html#7829

[Rumyra]

@estelle the HTML guidelines are here https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML if you wanted to update to reflect your changes above 👍

[teoli2003]

It will be very interesting to turn this rule on once done. That way, no PR could be merged with a missing alt attribute. That won't guarantee the quality of the attribute's value, but at least its existence.

[rubiesonthesky]

Are you interested in PRs for

• fix single quotes in html to double quotes
• add missing lang attribute in html element

I can submit some. Found by eslint and html plugin. :)

[teoli2003]

Are you interested in PRs for

* fix single quotes in html to double quotes

These will be fixed automatically by Prettier (soon I hope), so that's not useful (as we will have to run Prettier anyway)

* add missing lang attribute in html element

I would gladly review such PRs (with 50-100 entries each)

[Elchi3]

Thanks for filing this OWD project proposal!

Can we clarify the scope here?

Is this about updating https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML ?

Or about fixing all of MDN with regards to these best practices? (seems too large for a single project)

Or is the idea to invest into tooling to make sure HTML best practices are enforced? If so, is there a plan for this work?

[Elchi3]

In yesterday's planning call we agreed that there are too many things at once in this project proposal.

It would be good to:

• Finish the alt attribute project (maybe still have a new project on this one, so we make sure we go to end for all missing alt attributes)
• Maybe choose a second HTML best practice from the list and do a community outreach again so we crowd source fixing it , again. (from the list above, choose something important and crowd source-able).

Assigning @estelle to prepare these two new HTML best practice project proposals.

[CBID2]

Is this issue still open? I want to try and help solve it.

[Elchi3]

@estelle Is there still work left here?

[estelle]

Yes, Only the checked topics are done. The ones without checkmarks have not been confirmed.

On the last task: I do not know how to include a caption on tables in markdown.

[CBID2]

Yes, Only the checked topics are done. The ones without checkmarks have not been confirmed.

On the last task: I do not know how to include a caption on tables in markdown.

I’ll try it @estelle

[CBID2]

Yes, Only the checked topics are done. The ones without checkmarks have not been confirmed.
On the last task: I do not know how to include a caption on tables in markdown.

I’ll try it @estelle

Hey @estelle, can you provide me the link to the file we're changing?

[estelle]

It's all of MDN, starting with content/tree/main/files/en-us/web

It's a large job, but manageable in pieces. I recommend picking one sub-task, such as type="number" in Every form control should have an id doing a search for type="number", then, if there are at least 5 edits, submitting a PR for that subtask.

It is best, when starting out, to do smallish PRs. But, you don't want to do a PR for every change either, because then it takes longer to do the "admin" for the PR then actually editing the code. It's a balance. For example, if there are more that 20 files edited, perhaps do a PR for the CSS directory and another for the HTML directory.

Hope that helps, and thank you for helping!

[CBID2]

It's all of MDN, starting with content/tree/main/files/en-us/web

It's a large job, but manageable in pieces. I recommend picking one sub-task, such as type="number" in Every form control should have an id doing a search for type="number", then, if there are at least 5 edits, submitting a PR for that subtask.

It is best, when starting out, to do smallish PRs. But, you don't want to do a PR for every change either, because then it takes longer to do the "admin" for the PR then actually editing the code. It's a balance. For example, if there are more that 20 files edited, perhaps do a PR for the CSS directory and another for the HTML directory.

Hope that helps, and thank you for helping!

Hi @estelle! Here's my PRfor the caption issue. I only did one for now. Let me know if I'm one the right track. 😄

[CBID2]

content/tree/main/files/en-us/web

Hi @estelle! 😄 I found an area to add a caption element. Here's the PR for it. I had writer's block in coming up with an intriguing title, so feel free to revise it.

[CBID2]

I think I made an error in this PR. I'm not quite sure what "Markdownlint (PR files)" means. Can someone help?

[CBID2]

I need assistance with this PR. It keeps saying "Markdownlint (PR files)" in spite of my formatting attempts.

[teoli2003]

I think this has been automatically closed as #25612 had "Resolved #115" in it (It should have been something like "Part of #115" as it is not actually solving all of it. Reopening.

[CBID2]

I think this has been automatically closed as #25612 had "Resolved #115" in it (It should have been something like "Part of #115" as it is not actually solving all of it. Reopening.

Made the change @teoli2003

[CBID2]

Hey @estelle. I've noticed that only 29 of the 63 tasks are completed, so I think it would be best to reopen this issue.