Content: Should we have a policy for if/when attributes can be documented in their own MDN sub-articles?

[sideshowbarker]

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.

https://github.com/mdn/browser-compat-data/pull/6014#issuecomment-618779155 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).

[chrisdavidmills]

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.

[Ryuno-Ki]

Once some kind of agreement emerges, I'd like to also see a common structure recommended to make the documentation feel coherent.

[Ryuno-Ki]

Since I learned about the editorial page today (which linked the following): How much of the policy is covered by https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types already?