Where to use inline status macros?

[OnkarRuikar]

Background

• https://github.com/orgs/mdn/discussions/482
• Synchronize with BCD v5.5.14 content#32594 (comment)

---

Should we use the same strategy to lay inline status macros that we decided for {{securecontext_inline}} macro? If no, then what should be the strategy? This was discussed in a meeting and the decision was that the status and secure context macros are not the same and we need a broader discussion to decide about status macros.

For simplicity, I am using experimental status throughout the discussion but the same things should apply to deprecated and non-standard statuses too.

Following are the two strategies one of which could be used to lay inline status macros:

1. Christmas tree 🎄

• If a web feature (interface/CSS property) is experimental
  a. tag the page with experimental header macro
  b. also tag each member/value with experimental badge

2. Traffic light 🚥

• If an interface/CSS property is experimental
  a. Tag the page with experimental header macro
  b. Don't tag the individual members with the experimental badge

Following remain the same for both the strategies:

• If part of the feature is experimental
  a. don't use the header macro
  b. use experimental badge on experimental members/values
• Tag property/method pages with secure context, irrespective of the interface

---

Pros of Christmas tree 🎄 strategy

• Status information is a must unlike secure context (which is good to know). So the information needs to be easily discernible.
• No cognitive burden on readers: You land on a CSS value section from search engine and you look at all the status badges on the same line. No need to scroll up to look at page banners or no need to scroll down to look at the BCD table. Keeping info near is more useful, for proof refer the discussion.
• Conformity with BCD: All the statuses on the page will match exactly same with the BCD table below. Thus BCD remains single source of truth. And all compatibility issues will be tracked in BCD table.
• Automation friendly: Sync bot just has to mimic BCD data.
• Easy to enforce: Reviewers won't have to worry about checking if any complex rule is broken.
• Content is using this strategy currently. So there will be no change if we choose this option.

Cons of Christmas tree 🎄

• Time consuming if have to be done by hand. This is not an issue as bot already does the work.
• May look crowded/verbose. Could be subjective as inline status badges are small icons many won't complain.

Pros of Traffic light 🚥

• Concise. Few badges on the page.
• Add more prose here...

Cons of Traffic light 🚥

• What is the point of having inline status badges if readers would have to scroll down to see BCD table or page header banners to know the status of an interface member or CSS property value? If readers find it complex, then they may naturally start ignoring inline badges and start going straight to BCD table.
• Scrolling down or up could get annoying on long pages.
• This could get bit confusing for readers when multiple status badges are in play e.g. experimental and non-standard.
• Till now it has been Christmas tree for all status badges. How to effectively educate readers of this rule?
• Interface members/property values may not match BCD table exactly. So readers may complain using GitHub issues.
• Bot code will be a bit complex and reviewing bot generated sync PRs won't be that simple.
• Need a validation tool in PRs to check if a contributor has accidentally violated this rule. Which is easy to do till the strategy is not widely known.

---

Keeping it consistent for all the inline badges.

1. Read-only badge has to be added on each property and can't be summed up at page top using a header banner. So, for {{ReadOnlyInline}} macro it has to be Christmas tree 🎄 strategy. So to keep it consistent across all the inline badges(secure ctx and status), all the badges need to have Christmas tree strategy.
2. If we choose Christmas tree 🎄 strategy for inline status macros then, for sake of consistency we need to change secure context strategy to Christmas tree as well. Secure context macros are also going to get automated so there won't be any burden on humans.
3. Or can we live with different approaches for secure context and status macros? We can still change secure context strategy as it has not been implemented fully in content yet.

[hamishwillee]

To keep in mind about current rules:

1. Only one header macro is added to a page, even multiple apply of: deprecated, non-standard, or experimental. The macros are added in that order - i.e. always add deprecated if it is deprecated. Otherwise fall back to non-standard. This is true for both the top level and individual properties/methods.
2. Irrespective of what the header macro does, in an overview page all the status that apply to the properties are listed - so you'd get all of experimental/deprecated/non-standard on each property
3. You also get all of the status badges for properties in the Web API sidebar (from status metadata) but this may not be true for other sidebars.

The reason for the above rules was that the header macros for the status were too big/numerous. It was decided that we didn't need all that status at the top level - it if's deprecated then people shouldn't be using it -whether or not it is also non-standard. They could drill down for detail.

So the current rules are not quite as stated, and that makes a difference for comparison of the christmas tree vs traffic light approach.

FWIW I think that consistency is important. We chose the status rules to reduce clutter, but IMO if we're sticking with our status header macro approach then we would be better to apply the secure context header in all cases where it applies - both top of the page and on all the properties/macros to which it applies.
Note that we get header stuff fixed up as is currently in discussion, having the header macro isn't the problem we see it to be now, and I don't see the small badges on the properties to be obtrusive.

[OnkarRuikar]

Only one header macro is added to a page, even multiple apply of

Could you point me to the source? I don't think this is being followed:

• https://developer.mozilla.org/en-US/docs/Web/API/Metadata
• https://developer.mozilla.org/en-US/docs/Web/API/DirectoryEntrySync

At the moment, for status macros, we are pretty much garnishing the Christmas trees 🎄.

IMO if we're sticking with our status header macro approach then we would be better to apply the secure context header in all cases where it applies - both top of the page and on all the properties/macros to which it applies.

I agree.

[hamishwillee]

I don't know if it is documented - many things aren't, but it is definitely the rule :-). It makes sense too. I don't think there was ever a big project to tidy things up through.

IMO it is a good rule too given the current state of headers. But if we find a more compact strategy for headers, then having all of them would makes sense to me.

I like the Christmas tree too. Its consistent, which makes things easier for parsers and for readers. But as discussed previously, I'd prefer all these things to be done via metadata and the rendering sorted out separately. No inline macros or whatever at all in source.

[OnkarRuikar]

I vote for the first option Christmas tree 🎄 for both status and secure context macros.

[hamishwillee]

The only drawback I see is that people may try to edit it manually.

Yes. It would be much nicer added (say from metadata) in the rendering phase so that there is nothing visible to edit.

[dipikabh]

My vote is for 🎄 to include inline status, added by automation, to match BCD and to provide information to readers closer to the context.
(Reminder for us that if implemented, Status and compatibility indicators and page templates will need updating to state the automated nature.)

I am guessing we will not be able to extend this strategy to {{Optional_inline}} and {{ReadOnlyInline}} - or are we planning to include this info in BCD as well to be automatically added inline to content?

[teoli2003]

The data needed for {{Optional_inline}}and {{ReadOnlyInline}} is available in webidl (and therefore w3c/webref). So we could maintain them by automation, too.

But that's a separate project (the condition is always to have mdn/content pages that follow strictly the correct structure).

[hamishwillee]

So is anyone opposed?

[OnkarRuikar]

So is anyone opposed?

No one so far. Everyone loves Xmas.

[OnkarRuikar]

In the community meeting on 27th March following things have been discussed:
a. A brief overview was given about the issue.
b. Dipika gave 👍 to 🎄
c. People need more time to go through the entire thing. So the decision couldn't be made in the meeting.
d. Mozilla team to get back later and convey the decision here.

[estelle]

Time to vote!

Please add the following one of the two emojis by clicking on the smiley face next to the "Mark as answer":

Prefer xmas tree: select PARTY
Prefer streetlight: select HEART

[Josh-Cena]

Is this vote only about landing pages for CSS modules and API interfaces? What about:

• Experimental accepted values of experimental CSS properties?
• Experimental attributes of experimental HTML elements?
• Experimental accepted values of experimental HTML attributes?
• Experimental parameters of experimental API methods?
• Experimental accepted values of experimental API method parameters?

All of these cases don't have links/macros to subpages so it's hard to automate. How much does it cascade down the nested dls?

[OnkarRuikar]

Is this vote only about landing pages for CSS modules and API interfaces?

This is for everything. I would love to simply mirror BCD: If a value is there there in BCD it would be in content as inline macros, if it's not there, and you want it, then you need to submit a PR to add it to BCD and content will be updated automatically by a bot.

Experimental parameters of experimental API methods?

Could you give an example?

[Josh-Cena]

Well, all parameters of an experimental method are experimental by definition, if you consider members of experimental interfaces to also be experimental.

There are examples of experimental parameters of non-experimental methods too, for example, the options parameter of the ArrayBuffer constructor used to be one.

Using BCD makes sense, since BCD doesn't mark subfeatures by default unless they have different support than the base feature.