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:
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).