Compat banner prototype / research

[Elchi3]

User story

As a web developer, I want to quickly get answers whether or not I can use a Web feature, so I can develop compatible web sites and apps. As an MDN writer I want to present a single banner at the top of pages and that contains the relevant info automatically.

Acceptance criteria

A plan is made about banners at the top of MDN pages with research taken into account.

[Elchi3]

Banner messaging on MDN reference pages

This project was previously referred to as "Compat ribbon" or "Summary compat data".

Problems we are trying to solve

• People who come to MDN for compat data have comparatively low task completion rates (at 75%). We should aim to increase it by improving the compat tables and the banner messaging.
• Compat data is not only the table at the bottom, our banners are important, too. The user interviews have shown that some people would even stop reading any further if they encounter "Non-standard" or "Experimental tech" banners, because the API is unusable for them in that case. So, we should really be showing banners correctly and have real rules when they appear.
• Right now, we have a lot of different banners at the top of MDN pages. Sometimes several banners at once taking up a lot of space. The top of the page is very prominent real estate and we should be more deliberate about what messaging we present to our readers there, especially if they pay more attention to the banner than to the compat table.
• The "Experimental tech" banner was especially called out frequently as being wrongly placed oftentimes.
• BCD should be the source of truth for compat information and shouldn't be different to what banners say.
• Besides compatibility, any accessibility, security, privacy and/or performance concerns should be called out prominently as well in banners (see notes from MDN London meeting "Accessibility & performance impacts everything"). Educating about these aspects is also in the interest of the MDN or the Mozilla mission.

Possible solution: {{Banner}} macro

To address the above problems, we're currently thinking about introducing a new macro called Banner.ejs and also remove any other current banner macros.

Specification for the Banner macro

The {{Banner}} macro could work according to these rules:

1. If there is a headline on the page about a specific concern, display a generic text with a skip link to the concern section.

   • Concerns can be "Accessibility concerns", "Security concerns", "Privacy concerns", "Performance concerns". The headlines must be named exactly like this.

2. If the feature is experimental according to BCD, display a note about experimental technologies and their stability or compat implications. Link to the compat table. (I'm not sure how useful this one is, if we implement rule 4).

3. If the feature is deprecated or non-standard according to BCD, display a warning that this technology shouldn't be used anymore. Link to section "Standardized alternatives" (or similar) which will explain the deprecation and/or mention standard alternatives.

4. If the feature is not supported by major browsers (Chrome, Edge, Firefox, Safari, [Nodejs if JS]), display a simplified compat warning as a heads up and link to the compat table for more details.

   • Support is very fine grained in the main BCD table. For the banner we will simplify what support means:
     • If support is present in the last 5(?) versions of a browser or support is true, issue no compat warning for the given browser.
     • Ignore notes, sub features, and support ranges (only look into the first range).

If none of the above 4 rules applies to a feature, {{banner}} is a no-op and won't show any messaging. In other words, the feature can probably be used without trouble in terms of accessibility, security privacy, performance and compatibility.

If two or more of the above rules apply, we shouldn't be displaying many banners below each other like we do now, but have the banner so that several warning icons appear next to each other, for example. This is something we will need to figure out when designing the banner.

Removing old banners

The following banner macros should be replaced by {{Banner}} and so we will hopefully free up some space at the top reference pages:

• h1_gecko_minversion
• h2_gecko_minversion
• h3_gecko_minversion
• gecko_callout_heading
• fx_minversion_note
• gecko_minversion_header
• deprecated_header
• B2GOnlyHeader2
• non-standard_header
• SeeCompatTable
• ... (possibly more)

Design

There is no mockup for the look and feel of the new banner yet. From conversations it seems like:

• Icons would be great.
• The banner shouldn't take much space and should be really concise in its messaging. It links to sections with the gory details.
• It should be very consistent so that muscle memory can be built when seeing it at the very same place on MDN reference pages.

Next steps

• Collect feedback on the {{banner}} idea. (we are here)
• If needed, refine the initial specification (see above) for when it should appear.
• Create a design and a prototype.
• Get user feedback on the prototype.
• Implement/finalize {{Banner}}.
• Roll it out to a set of docs (e.g. CSS docs).
• Go/no-go decision for all docs.

[wbamberg]

I think this seems like a very sensible approach :).

A couple of general points coming out of the KS analysis work I've been doing.

• Should we add "Available only in secure contexts" and maybe "(not?) Available in workers"? I suppose we could always extend the macro to handle these later.

• What about badges? Badges are like banners, except they are inline and appear on a different page to the page they refer to (if you see what I mean). Should we have a {{Badge}} macro that works along similar lines? (I don't like this idea, because it's an inline macro). Should we just deprecate badges?

Concerns can be "Accessibility concerns", "Security concerns", "Privacy concerns", "Performance concerns". The headlines must be named exactly like this.

How will this work in pages outside the en-US locale?

2. If the feature is experimental according to BCD, display a note about experimental technologies and their stability or compat implications. Link to the compat table. (I'm not sure how useful this one is, if we implement rule 4).

I agree that (2) might not be needed, given (4).

Support is very fine grained in the main BCD table. For the banner we will simplify what support means

I think we'll have to work through the details of this. It's tricky, and seeing how it will look will help. For example:

If support is present in the last 5(?) versions of a browser or support is true, issue no compat warning for the given browser.

Maybe a date-based approach would work better? If this has been supported for > 1 year, issue no warning? I think we can do that with https://github.com/mdn/browser-compat-data/tree/master/browsers, no?

Ignore notes, sub features, and support ranges (only look into the first range).

Again tricky. Sometimes notes are important, sometimes they're not. I think we'd have to see how it feels.

If two or more of the above rules apply, we shouldn't be displaying many banners below each other like we do now, but have the banner so that several warning icons appear next to each other, for example. This is something we will need to figure out when designing the banner.

I'm a little bothered about an icon-based approach - at least I'm conflicted. I like the idea of saving space but worry they won't be understandable. Which is a way of saying that the design will be hard I suppose.

h1_gecko_minversion
h2_gecko_minversion
h3_gecko_minversion
gecko_callout_heading
fx_minversion_note
gecko_minversion_header

I would just delete all these without waiting for a replacement :).

Also, I guess {{Banner}} takes an argument that's a path through BCD?

[chrisdavidmills]

This looks like a really good start Florian. I had a bunch of comments, but then Will already asked most of the questions I had ;-) I guess I've got a few extra bits to chime in, so here goes.

Should we add "Available only in secure contexts" and maybe "(not?) Available in workers"? I suppose we could always extend the macro to handle these later.

I was going to ask exactly this ;-) I guess the trouble is that these details have no representation in BCD, and for good reason (we want to keep BCD pure, and not pollute it with every little thing). So maybe we'd have to include a couple of extra parameters in the macro to handle this, which would be messy and suboptimal...I don't know. An extensible options object would be probably cleaner than however many parameters...but I guess this is a conversation for slightly later on.

The good news is that most features are available in web workers, and the web is largely moving towards HTTPS everywhere, so most things will be running in a secure context. It's more likely that we'll have to call out things that don't run in workers/secure contexts.

Concerns can be "Accessibility concerns", "Security concerns", "Privacy concerns", "Performance concerns". The headlines must be named exactly like this.

How will this work in pages outside the en-US locale?

This is a good point. I guess we'd need some kind of l10n object to look for the correct string based on locale.

I'm a little bothered about an icon-based approach - at least I'm conflicted.

I hear your concern here, although I'm thinking this could be good for international reach, especially if we use very common icons, like padlock for security, etc.

Another option would be to just have a simple line of text links, equally spaced using flexbox, e.g.

Concerns — Accessibility | Privacy | Performance | Security

[chrisdavidmills]

And for the banners, don't forget

{{AvailableInWorkers}}
{{securecontext_header}}

[Elchi3]

Thanks for your feedback, Will and Chris!

Should we add "Available only in secure contexts" and maybe "(not?) Available in workers"?

I think for now, my answer would be no, lets not special case them. I think banner messaging should be about critical limitations the user of the feature needs a heads up about. I'm not sure HTTPS and workers qualify as being more special here than other security or performance concerns. Maybe it could be mentioned in the security concerns section that a feature is HTTPS only? I agree with Chris that HTTPS-only and worker availability will become the norm anyway, so it will be even less worth calling these out separately.

What about badges? Badges are like banners, except they are inline and appear on a different page to the page they refer to (if you see what I mean). Should we have a {{Badge}} macro that works along similar lines? (I don't like this idea, because it's an inline macro). Should we just deprecate badges?

I think we should just deprecate these kinds of badges, but I also think we should scope this project to banners and deal with badges in a new project or a separate discussion. Can't do everything at once. If this approach works for banners, we might be able to re-use it for badges, but I think it would be good to look into badges on their own.

How will this work in pages outside the en-US locale?
This is a good point. I guess we'd need some kind of l10n object to look for the correct string based on locale.

Yes, I think we should use current KumaScript l10n mechanisms to localize this approach, even if we're not happy with how that works.

I agree that (2) might not be needed, given (4).

There is also mdn/browser-compat-data#1528, so I think we should go ahead and remove "experimental" when we have rule 4 working.

Maybe a date-based approach would work better? If this has been supported for > 1 year, issue no warning? I think we can do that with https://github.com/mdn/browser-compat-data/tree/master/browsers, no?

Yes, that might work better. I think this rule isn't straight forward and will need some playing around with until we get it right. I think it should answer the question "Can I use this?" basically.

I'm a little bothered about an icon-based approach - at least I'm conflicted. I like the idea of saving space but worry they won't be understandable. Which is a way of saying that the design will be hard I suppose.

Yes, we will need some clever design thinking here. I share your concerns, but I do hope that we will be able to come up with something.

I would just delete all these without waiting for a replacement :).

Yes, feel free! :) Didn't mean to sound like {{banner}} is a prerequisite for all of them.

Also, I guess {{Banner}} takes an argument that's a path through BCD?

Yes!

I'm going to update the above spec for banner based on the feedback here. Let me know if you have more thoughts. I think the hard parts (or the parts we're still undecided) are:

• coming up with an exact implementation for rule 4,
• the design of this,
• and whether or not to deal with https/workers as a special case.

[chrisdavidmills]

and whether or not to deal with https/workers as a special case.

I really like your idea of just adding these to the "concerns" sections. They could definitely fit under performance/security.

[wbamberg]

On secure-contexts-only and available-in-workers: I don't think we should use parameters for this. I think we should get away from that model and towards one where the "macro" (or whatever it ends up being :) finds the answer in some properly-maintained data source (e.g. BCD or mdn/data). Just like {{Compat}}. So one suggestion would be to include this data in mdn/data (and that's the suggestion made in the KS landscape doc in fact) and have {{Banner}} find it there.

But, I agree we shouldn't worry about this now, and also that we should carefully consider which data to include in here. In particular we should avoid a situation where a condition is true for 90% of pages (because then it just becomes noise - the value of these banners is that you notice them when they are present, because they are usually absent).

[a2sheppy]

Before I get started with my thoughts, I'd like to start by saying this is a great beginning. I'm very excited about this!

1. If there is a headline on the page about a specific concern, display a generic text with a skip link to the concern section.
   
   * Concerns can be "Accessibility concerns", "Security concerns", "Privacy concerns", "Performance concerns". The headlines must be named exactly like this.

Another option would be to have the ability to specify the links to the documentation about each of these topics within the JSON tables somewhere. This would allow more flexibility, such as the ability to have an entire article covering security concerns for an API that has many of them.

If none of the above 4 rules applies to a feature, {{banner}} is a no-op and won't show any messaging. In other words, the feature can probably be used without trouble in terms of accessibility, security privacy, performance and compatibility.

I think we should avoid ambiguity and inconsistency and always display at least the true/false compatibility information.

If two or more of the above rules apply, we shouldn't be displaying many banners below each other like we do now, but have the banner so that several warning icons appear next to each other, for example. This is something we will need to figure out when designing the banner.

I agree; the banner should be some sort of an icon or widget bar. General warnings on one end (deprecated, non-standard, etc) and per-browser usability widgets on the other end. Something like:

(Experimented with a couple of approaches to indicating "not supported" on the Opera icon there)

Tooltips over each of the icons would provide additional details; this could be as simple as explaining what "Non-standard" means to providing more detailed information about compatibility in the browser you're pointing at.

[wbamberg]

One other thing I'm worried about here is that to me the effectiveness of these banner items is greater if they only appear on a small number of pages - so you notice them when they are there. If they appear on, say 80% of pages, they are not so effective, they are just generally part of the page nav, and then they are fighting with other elements like the "jump to" thing for instance. It seems likely that some of these "XYZ concerns" sections will appear on a lot of pages.

[a2sheppy]

One other thing I'm worried about here is that to me the effectiveness of these banner items is greater if they only appear on a small number of pages - so you notice them when they are there. If they appear on, say 80% of pages, they are not so effective, they are just generally part of the page nav, and then they are fighting with other elements like the "jump to" thing for instance. It seems likely that some of these "XYZ concerns" sections will appear on a lot of pages.

Will, that's definitely a valid point. Perhaps instead of overloading the compat bar with the warning/advisory/concerns information, we should find a separate method for handling those.

One possibility that keeps coming back into my head is the idea of having a vertically-oriented bar that lays along the edge of the article area. This would extend the full height of the article, and could display warning icons in it; this bar would only be present on pages for which concerns exist. This bar could even have functionality to present added details alongside the article providing more depth, if clicked/hovered/whatever.

Anyway, implementation specifics aside, it might be worth exploring how to present these in two separate places, for the reasons Will stated.