Attributes documentation for HTML input elements is confusing

[wbamberg]

See https://discourse.mozilla.org/t/attributes-for-input-elements/43899.

We should give each input element its own "Attributes" list including all the attributes it supports (apart from the real global ones) and scrap the "Supported common attributes" row in the blue box.

MDN URL: https://developer.mozilla.org/en-US/docs/Web/HTML

[rachelandrew]

@chrisdavidmills I just wanted to check my understanding of this task. We need to make sure the list on the input page lists all attributes. Then each individual page should show all of the attributes that apply to that type?

[chrisdavidmills]

Yup, that sounds about right.

And then in the blue box near the top of each input type page, delete the "Supported common attributes" row.

[sideshowbarker]

@estelle Are you still planning to work on this one?

[estelle]

Hoping to do it Q3

[Rumyra]

Converting this into a discussion as there's conflicting solutions here and in the owd project which should be discussed here openwebdocs/project#114

[Rumyra]

Specifically

What is important, though, is not to have an HTML/Attributes/ hierarchy but an HTML/Element/name/Attributes/name hierarchy, like in BCD. (Except for the global attributes of course).

[Rumyra]

Also related to this is a previous discussion which you can find here #206

Notably:

sideshowbarker
on 25 Apr 2020
Should all documentation for an attribute specific to a particular element be included within the MDN article for the element it belongs to? Or is it sometimes OK to create sub-articles related to such attributes? And if it is sometimes OK to have sub-articles for attributes, what criteria should we follow when trying to decide whether a particular attribute merits its own sub-article?

I think there are some specific cases in which splitting out some attribute documentation into sub-articles can clearly improve the content. But in general it also has some visible advantages: Specifically, it allows the MDN documentation for an attribute to:

have its own Specifications table and spec URL
have its own Browser Compatibility table
Case in point: name attribute for meta element

Here’s one concrete example: A couple days ago, I split out some MDN documentation related to the name attribute of the meta element into its own sub-article:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name

In fact, I went even deeper than that and also created another sub-article one more level down:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color

And in reviewing a related BCD change I also made, @Elchi3 pointed out:

I wonder if we have agreement on page structures on MDN. So far, the HTML reference documentation has pages for HTML elements and maybe sometimes pages for attributes. You've decided to go deeper and create pages for more attributes and specific values. This might make sense, but I would like it to be discussed.

So, I’m raising this issue here for discussion.

mdn/browser-compat-data#6014 (comment) has some rationale for creating those sub-articles.

But to also elaborate here on the rationale: one detail I want to mention is that the title I gave to https://developer.mozilla.org/docs/Web/HTML/Element/meta/name is the same as the corresponding https://html.spec.whatwg.org/multipage/#standard-metadata-names spec section.

That title is Standard metadata names and it follows a precedent in that we already a similar https://developer.mozilla.org/docs/Web/HTML/Link_types article related to the rel attribute and the HTML spec https://html.spec.whatwg.org/multipage/#linkTypes section titled Link types.

I think name (for meta) and rel are special cases meriting special treatment, because both are:

attributes with their own spec section, with its own heading (Link types for rel, Standard metadata names for name)
attributes with the additional level of complexity of having standard sets of keyword values defined in the HTML spec
attributes with associated registries (https://wiki.whatwg.org/wiki/MetaExtensions and http://microformats.org/wiki/existing-rel-values)
As far as rel, having its own https://developer.mozilla.org/docs/Web/HTML/Link_types article seems clearly necessary, given it’s shared by multiple elements: a/area/link/form. Similarly, https://developer.mozilla.org/docs/Web/HTML/Attributes/autocomplete input/select/textarea with its own spec section; heading: Autofilling form controls: the autocomplete attribute.

As far as name for meta, it’s clearly not strictly necessary for it to have its own sub-article — but I think the main criterion for using a sub-article structure for it is: it’s so obviously similar to other cases (rel, autocomplete) that MDN already uses a sub-article structure for (as outlined above).

And

chrisdavidmills
on 27 Apr 2020
I think it is totally fine to have separate pages for attributes. Before her contract finished, Estelle went on a bit of a mission and created a whole load of separate pages for input element attributes. The advantage here was that there are a lot of details to cover, and having them split up across separate pages can really help with structure and understanding, plus we have separate pages for the different input types, and there was quite a bit of repetition of attribute information.

We don't have rules for when an attribute (or individual value) warrants its own page, but given that @ddbeck / @Elchi3 / @wbamberg are working on page structures and linting for pages in the next gen of MDN, we should probably define some.

I'd suggest making them all optional, but there should be a set of criteria that provide pointers towards an attribute of individual value warranting its own page (lots of info to cover, needs separate BCD entry/entries, own section in spec, etc.). I also think we should OK attribute or individual value subpages, but draw the line at any further levels down that that? I think level is possibly a bit over the top.

[Rumyra]

The original list of html attributes is here mdn/content#1712 (comment)