-
Notifications
You must be signed in to change notification settings - Fork 22.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Should we have a policy for if/when attributes can be documented in their own MDN sub-articles? #1707
Comments
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. |
Once some kind of agreement emerges, I'd like to also see a common structure recommended to make the documentation feel coherent. |
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? |
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:
Case in point:
name
attribute formeta
elementHere’s one concrete example: A couple days ago, I split out some MDN documentation related to the
name
attribute of themeta
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:
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
(formeta
) andrel
are special cases meriting special treatment, because both are:rel
, Standard metadata names forname
)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/autocompleteinput
/select
/textarea
with its own spec section; heading: Autofilling form controls: the autocomplete attribute.As far as
name
formeta
, 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).The text was updated successfully, but these errors were encountered: