WebExtensions docs: styles for browser compatibility tables

[William Bamberg]

Hi dev-mdc and dev-addons

All the WebExtensions API docs now generate browser compatibility tables
from the JSON data, meaning we can aggregate the data in different ways and
expose it in different places.

There are currently 2 sorts of tables:

* tables at the level of individual parts of an API:
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/WebReques/onBeforeRequest#Browser_compatibility

* tables at the level of an API:
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/webRequest#Browser_compatibility

So far I've kept the same table style that's used in browser compat tables
in MDN. (for example:
https://developer.mozilla.org/en-US/docs/Web/CSS/margin#Browser_compatibility
).

But it's been suggested to me that, especially since we only have 1 mobile
browser, it would be better to show desktop and mobile browsers together,
rather than in a tabbed interface. So I poked at things a bit and came up
with this version: https://i.imgur.com/3cdIjJY.png.

What do you think? Is this better? Is it better enough to be worth making
the styles diverge from the open web docs?

Will

[Chris Mills]

I find it surprising that other mobile browsers can’t yet support WebExtensions (what about Mobile Chrome?) Even if this is the case, won’t other mobile browsers support them in the future?

I’m not sure if the overhead of implementing a different table now to then change it back to the other style later on is worth it?

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status

[Eric Shepherd]

I agree with Chris; this is going to change in the future, almost
certainly, so the table will become unwieldy if redone this way for
WebExtensions.

> I find it surprising that other mobile browsers can’t yet support WebExtensions (what about Mobile Chrome?) Even if this is the case, won’t other mobile browsers support them in the future?
>
> I’m not sure if the overhead of implementing a different table now to then change it back to the other style later on is worth it?

--

Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: https://www.bitstampede.com/
Twitter: http://twitter.com/sheppy
Doodle: http://doodle.com/the.sheppy

[William Bamberg]

On Mon, Apr 18, 2016 at 10:06 AM, Chris Mills <cmi...@mozilla.com> wrote:

> I find it surprising that other mobile browsers can’t yet support
> WebExtensions (what about Mobile Chrome?)

As far as I know, no.

> Even if this is the case, won’t other mobile browsers support them in the
> future?
>

It's possible. I haven't heard any concrete plans for this. (I'd love to
know :)

But there is space for a couple of mobile browsers in this design, so even
if Chrome and Edge added support, I don't think that would force a
table-redesign.

>
> I’m not sure if the overhead of implementing a different table now to then
> change it back to the other style later on is worth it?
>

I don't think this is a good argument for not doing this. Since the table
is built using a macro, and the table's already designed, then the
"overhead" of changing, and changing back, is really small. Just updating
the macro to build a different table.

Keep in mind that there (very probably) *will be* a redesign of this table
(and all the other tables) coming up in the next 1-2 years, as the
BrowserCompat project will affect the style of all our tables. This is true
whether or not some mobile browsers start supporting WebExtensions. So I'm
fully expecting the style to change, and don't expect it to be a big
problem.

Will

[Sebastian Zartner]

Generally I like that new approach to automatically generate the tables.
Good job on that, Will!

On 19 April 2016 at 01:36, William Bamberg <wbam...@mozilla.com> wrote:

> On Mon, Apr 18, 2016 at 10:06 AM, Chris Mills <cmi...@mozilla.com> wrote:
>
> > I find it surprising that other mobile browsers can’t yet support
> > WebExtensions (what about Mobile Chrome?)
>
>
> As far as I know, no.
>

Even when it's the case that only Firefox supports these features at the
moment, I believe the other ones should be listed, too. Otherwise the
statement about them is unclear, as it can either mean they don't have them
implemented or their implementation status is unknown. Also, it doesn't
allow to add notes for them.

> I’m not sure if the overhead of implementing a different table now to then
> > change it back to the other style later on is worth it?
>
> I don't think this is a good argument for not doing this. Since the table
> is built using a macro, and the table's already designed, then the
> "overhead" of changing, and changing back, is really small. Just updating
> the macro to build a different table.
>
> Keep in mind that there (very probably) *will be* a redesign of this table
> (and all the other tables) coming up in the next 1-2 years, as the
> BrowserCompat project will affect the style of all our tables. This is true
> whether or not some mobile browsers start supporting WebExtensions. So I'm
> fully expecting the style to change, and don't expect it to be a big
> problem.
>

I wonder if we shouldn't already go further into the direction of the
Browser Compat project and let the macro built the new table (currently
generated by the {{EmbedCompatTable}} macro). People already put a lot of
thoughts and effort into their creation, so it would be great if we could
reuse them.

Sebastian

[Jean-Yves Perrier]

cc/ing Stephanie in this thread as she is our expert in this domain.

--
Jean-Yves Perrier
Senior St. Project Manager, Developer Documentation / MDN

[Eric Shepherd]

I agree; let's use the new approach to building these tables since we
have it. Gives us more flexibility and has us on the forefront of our
platform's structure. Additionally, it can be used to test and debug the
macros and techniques involved.

> I wonder if we shouldn't already go further into the direction of the
> Browser Compat project and let the macro built the new table (currently
> generated by the {{EmbedCompatTable}} macro). People already put a lot of
> thoughts and effort into their creation, so it would be great if we could
> reuse them.

[William Bamberg]

(meta: I've got lots of feedback here from the MDN side, but none from
dev-addons. I'd love to hear some views from that side. Or maybe noone from
that side cares much, and I should just drop it.)

On Mon, Apr 18, 2016 at 10:34 PM, Sebastian Zartner <
sebastia...@gmail.com> wrote:

> Generally I like that new approach to automatically generate the tables.
> Good job on that, Will!
>

Thanks Sebastian!

>
> On 19 April 2016 at 01:36, William Bamberg <wbam...@mozilla.com> wrote:
>
>> On Mon, Apr 18, 2016 at 10:06 AM, Chris Mills <cmi...@mozilla.com> wrote:
>>
>> > I find it surprising that other mobile browsers can’t yet support
>> > WebExtensions (what about Mobile Chrome?)
>>
>>
>> As far as I know, no.
>>
>
> Even when it's the case that only Firefox supports these features at the
> moment, I believe the other ones should be listed, too. Otherwise the
> statement about them is unclear, as it can either mean they don't have them
> implemented or their implementation status is unknown. Also, it doesn't
> allow to add notes for them.
>

On the particular topic of which browsers should be included in the tables
*today*: this was discussed back in November when I first built these
tables, and the consensus was the current set (plus Firefox OS, which I
have now removed).

The conversation did not happen in dev-mdc, so you didn't get to speak on
it, Sebastian. That was my fault, and I'm sorry about that.

However, I still not convinced that we should include every browser in
these tables.

We *should* document somewhere which browsers offer any support for
WebExtensions at all. But documenting it by writing "No" 300 times for
every such browser feels like overkill, and I think it would make the
tables harder to use for their actual purpose.

This is not like CSS, where every browser has some kind of support. Many
browsers currently don't support WebExtensions at all, and some probably
never will.

For example: the new-style tables (
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility)
include 13 different browsers. Only 5 of these currently support
WebExtensions at all, and 3-5 of them probably never will.

That's a lot of extra data, which doesn't convey very much extra
information.

(I could say, it would introduce the other sort of confusion, where someone
might think that because a table for an API includes a column for, say,
Safari on iOS, then Safari on iOS does have some kind of support for
WebExtensions, and some other APIs might be supported.)

> > I’m not sure if the overhead of implementing a different table now to
>> then
>> > change it back to the other style later on is worth it?
>>
>> I don't think this is a good argument for not doing this. Since the table
>> is built using a macro, and the table's already designed, then the
>> "overhead" of changing, and changing back, is really small. Just updating
>> the macro to build a different table.
>>
>> Keep in mind that there (very probably) *will be* a redesign of this table
>> (and all the other tables) coming up in the next 1-2 years, as the
>> BrowserCompat project will affect the style of all our tables. This is
>> true
>> whether or not some mobile browsers start supporting WebExtensions. So I'm
>> fully expecting the style to change, and don't expect it to be a big
>> problem.
>>
>

> I wonder if we shouldn't already go further into the direction of the
> Browser Compat project and let the macro built the new table (currently
> generated by the {{EmbedCompatTable}} macro). People already put a lot of
> thoughts and effort into their creation, so it would be great if we could
> reuse them.
>

I did look at these tables, and considered using them, but didn't for a few
reasons:
* they're totally different from the tables on almost all the other pages,
and I think consistency is a virtue here
* they don't lend themselves to "aggregate" tables, like
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/alarms#Browser_compatibility,
because there isn't space for the name of the API on the same line as the
row of green/red boxes
* this is more of a personal thing, but I like having the name of the
browser visible, not just an icon.

When BrowserCompat happens properly, we will have a single table design,
and WebExtensions will use that, for sure. In the meantime, sticking closer
to the other tables seems like a better idea.

[Sebastian Zartner]

On 20 April 2016 at 00:15, William Bamberg <wbam...@mozilla.com> wrote:

> On 19 April 2016 at 01:36, William Bamberg <wbam...@mozilla.com> wrote:
>>
>>> On Mon, Apr 18, 2016 at 10:06 AM, Chris Mills <cmi...@mozilla.com>
>>> wrote:
>>>
>>> > I find it surprising that other mobile browsers can’t yet support
>>> > WebExtensions (what about Mobile Chrome?)
>>>
>>>
>>> As far as I know, no.
>>>
>>
>> Even when it's the case that only Firefox supports these features at the
>> moment, I believe the other ones should be listed, too. Otherwise the
>> statement about them is unclear, as it can either mean they don't have them
>> implemented or their implementation status is unknown. Also, it doesn't
>> allow to add notes for them.
>>
>
>
> On the particular topic of which browsers should be included in the tables
> *today*: this was discussed back in November when I first built these
> tables, and the consensus was the current set (plus Firefox OS, which I
> have now removed).
>
> The conversation did not happen in dev-mdc, so you didn't get to speak on
> it, Sebastian. That was my fault, and I'm sorry about that.
>

No problem. Therefore I have the chance to speak up now.

However, I still not convinced that we should include every browser in
> these tables.
>
> We *should* document somewhere which browsers offer any support for
> WebExtensions at all. But documenting it by writing "No" 300 times for
> every such browser feels like overkill, and I think it would make the
> tables harder to use for their actual purpose.
>
> This is not like CSS, where every browser has some kind of support. Many
> browsers currently don't support WebExtensions at all, and some probably
> never will.
>

We have already a bunch of pages where support is limited to one or two
browsers and there is likely never support in other browsers like in
https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-points-x or
https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/API/Audio_Channels_API
.

In my opinion the compatibility tables should display the main browsers
everywhere by default (i.e. always have the same amount of columns like on
caniuse.com). The user may have the opportunity to (persistently) customize
the columns and display to his or her needs.

For example: the new-style tables (
> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility)
> include 13 different browsers. Only 5 of these currently support
> WebExtensions at all, and 3-5 of them probably never will.
>
> That's a lot of extra data, which doesn't convey very much extra
> information.
>
> (I could say, it would introduce the other sort of confusion, where
> someone might think that because a table for an API includes a column for,
> say, Safari on iOS, then Safari on iOS does have some kind of support for
> WebExtensions, and some other APIs might be supported.)
>

That's true, though I'd argue that when someone is at a specific API's
page, it's more likely that the person only cares about the support of that
API and not for general browser support of a feature.

> I’m not sure if the overhead of implementing a different table now to then
>>> > change it back to the other style later on is worth it?
>>>
>>> I don't think this is a good argument for not doing this. Since the table
>>> is built using a macro, and the table's already designed, then the
>>> "overhead" of changing, and changing back, is really small. Just updating
>>> the macro to build a different table.
>>>
>>> Keep in mind that there (very probably) *will be* a redesign of this
>>> table
>>> (and all the other tables) coming up in the next 1-2 years, as the
>>> BrowserCompat project will affect the style of all our tables. This is
>>> true
>>> whether or not some mobile browsers start supporting WebExtensions. So
>>> I'm
>>> fully expecting the style to change, and don't expect it to be a big
>>> problem.
>>>
>>
>> I wonder if we shouldn't already go further into the direction of the
>> Browser Compat project and let the macro built the new table (currently
>> generated by the {{EmbedCompatTable}} macro). People already put a lot of
>> thoughts and effort into their creation, so it would be great if we could
>> reuse them.
>>
>
>
> I did look at these tables, and considered using them, but didn't for a
> few reasons:
> * they're totally different from the tables on almost all the other pages,
> and I think consistency is a virtue here
>

Absolutely. See the points above.

> * they don't lend themselves to "aggregate" tables, like
> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/alarms#Browser_compatibility,
> because there isn't space for the name of the API on the same line as the
> row of green/red boxes
>

Yes, that's the cost of allowing to have more browsers listed. This could
be solved by putting them on the same line when there is enough horizontal
space, i.e. when only a few browsers are shown (but keep them on two lines
otherwise).

> * this is more of a personal thing, but I like having the name of the
> browser visible, not just an icon.
>

Same for me, actually I prefer text plus icons. That might be part of the
customization options.

When BrowserCompat happens properly, we will have a single table design,
> and WebExtensions will use that, for sure. In the meantime, sticking closer
> to the other tables seems like a better idea.
>

I see your macro as a first step towards a new approach to BrowserCompat.
That's the reason why I think using the new layout for them already makes
sense. Though it'd be ok for me to stick with the current table layout for
now for consistency reasons. We could still go the same direction as
{{EmbedCompatTable}} and only show the new layout to a selected group of
people and generate the old layout for the others.

[Mindaugas J.]

2016-04-20 1:15 GMT+03:00 William Bamberg <wbam...@mozilla.com>:

> (meta: I've got lots of feedback here from the MDN side, but none from
> dev-addons. I'd love to hear some views from that side. Or maybe noone from
> that side cares much, and I should just drop it.)
>

Alright, here are my 5c:

>
>
>> On 19 April 2016 at 01:36, William Bamberg <wbam...@mozilla.com> wrote:
>>
>>> On Mon, Apr 18, 2016 at 10:06 AM, Chris Mills <cmi...@mozilla.com>
>>> wrote:
>>>
>>> > I find it surprising that other mobile browsers can’t yet support
>>> > WebExtensions (what about Mobile Chrome?)
>>>
>>>
>>> As far as I know, no.
>>>
>>
>> Even when it's the case that only Firefox supports these features at the
>> moment, I believe the other ones should be listed, too. Otherwise the
>> statement about them is unclear, as it can either mean they don't have them
>> implemented or their implementation status is unknown. Also, it doesn't
>> allow to add notes for them.
>>
>

Chrome mobile had so much time to support webext without any movement until
now that I don't think it's ever happening. A quick search gives a bug from
year 2012: https://bugs.chromium.org/p/chromium/issues/detail?id=113111
which is in the perpetual assigned-but-abandoned state that I find so
typical on the chromium tracker. There's been a recent bug owner change but
I have no idea what significance it has, if any.

However, I still not convinced that we should include every browser in
> these tables.
>
> We *should* document somewhere which browsers offer any support for
> WebExtensions at all. But documenting it by writing "No" 300 times for
> every such browser feels like overkill, and I think it would make the
> tables harder to use for their actual purpose.
>
> This is not like CSS, where every browser has some kind of support. Many
> browsers currently don't support WebExtensions at all, and some probably
> never will.
>

> For example: the new-style tables (
> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility)
> include 13 different browsers. Only 5 of these currently support
> WebExtensions at all, and 3-5 of them probably never will.
>
> That's a lot of extra data, which doesn't convey very much extra
> information.
>
> (I could say, it would introduce the other sort of confusion, where
> someone might think that because a table for an API includes a column for,
> say, Safari on iOS, then Safari on iOS does have some kind of support for
> WebExtensions, and some other APIs might be supported.)
>

I completely agree with this reasoning.

[William Bamberg]

On Tue, Apr 19, 2016 at 11:44 PM, Sebastian Zartner <
sebastia...@gmail.com> wrote:

> On 20 April 2016 at 00:15, William Bamberg <wbam...@mozilla.com> wrote:
>
>> On 19 April 2016 at 01:36, William Bamberg <wbam...@mozilla.com> wrote:
>>>
>>>> On Mon, Apr 18, 2016 at 10:06 AM, Chris Mills <cmi...@mozilla.com>
>>>> wrote:
>>>>
>>>> > I find it surprising that other mobile browsers can’t yet support
>>>> > WebExtensions (what about Mobile Chrome?)
>>>>
>>>>
>>>> As far as I know, no.
>>>>
>>>
>>> Even when it's the case that only Firefox supports these features at the
>>> moment, I believe the other ones should be listed, too. Otherwise the
>>> statement about them is unclear, as it can either mean they don't have them
>>> implemented or their implementation status is unknown. Also, it doesn't
>>> allow to add notes for them.
>>>
>>
>>

>> On the particular topic of which browsers should be included in the
>> tables *today*: this was discussed back in November when I first built
>> these tables, and the consensus was the current set (plus Firefox OS, which
>> I have now removed).
>>
>> The conversation did not happen in dev-mdc, so you didn't get to speak on
>> it, Sebastian. That was my fault, and I'm sorry about that.
>>
>
> No problem. Therefore I have the chance to speak up now.
>

> However, I still not convinced that we should include every browser in
>> these tables.
>>
>> We *should* document somewhere which browsers offer any support for
>> WebExtensions at all. But documenting it by writing "No" 300 times for
>> every such browser feels like overkill, and I think it would make the
>> tables harder to use for their actual purpose.
>>
>> This is not like CSS, where every browser has some kind of support. Many
>> browsers currently don't support WebExtensions at all, and some probably
>> never will.
>>
>

> We have already a bunch of pages where support is limited to one or two
> browsers and there is likely never support in other browsers like in
> https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-points-x or
> https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/API/Audio_Channels_API
> .
>

I don't think these are analogous to this situation.

scroll-snap-points-x is one single, deprecated, property in a technology
(CSS) that has very widespread browser support in general. A WebExtensions
analogue of scroll-snap-points-x would be something like
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/extension/sendRequest,
which will never be supported in Firefox - but I'm not proposing to remove
Firefox from the compat table here.

The Audio Channels API is actually now under /Mozilla, not /Web, so I *do*
think having cross-browser compatibility tables is not helpful (I think it
used to have them when we expected that the API might become standardised,
so other browsers might support it. Now we are fairly sure they won't, yes,
we should remove them IMO).

A closer analogue would be something like, why don't we include Lynx in
browser compat tables for CSS?

>
> In my opinion the compatibility tables should display the main browsers
> everywhere by default (i.e. always have the same amount of columns like on
> caniuse.com). The user may have the opportunity to (persistently)
> customize the columns and display to his or her needs.
>

I feel as if customization is a bit of a red herring here. I don't have the
ability to implement this (it would take platform support) and as we all
know, defaults are powerful things, so even if it were possible, choosing
optimal defaults would still be worth arguing over :).

>
> For example: the new-style tables (
>> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility)
>> include 13 different browsers. Only 5 of these currently support
>> WebExtensions at all, and 3-5 of them probably never will.
>>
>> That's a lot of extra data, which doesn't convey very much extra
>> information.
>>
>> (I could say, it would introduce the other sort of confusion, where
>> someone might think that because a table for an API includes a column for,
>> say, Safari on iOS, then Safari on iOS does have some kind of support for
>> WebExtensions, and some other APIs might be supported.)
>>
>

'when only a few browsers are shown' - do you mean, by default show all
browsers, but let the user exclude browsers, and if they exclude enough to
fit the API name on the same line, then do so?

But that means that by default, the aggregate table is not scannable. This
just doesn't seem like a good experience.

>
>
>> * this is more of a personal thing, but I like having the name of the
>> browser visible, not just an icon.
>>
>
> Same for me, actually I prefer text plus icons. That might be part of the
> customization options.
>
> When BrowserCompat happens properly, we will have a single table design,
>> and WebExtensions will use that, for sure. In the meantime, sticking closer
>> to the other tables seems like a better idea.
>>
>
> I see your macro as a first step towards a new approach to BrowserCompat.
> That's the reason why I think using the new layout for them already makes
> sense. Though it'd be ok for me to stick with the current table layout for
> now for consistency reasons. We could still go the same direction as
> {{EmbedCompatTable}} and only show the new layout to a selected group of
> people and generate the old layout for the others.
>

I'm very happy to be an early adopter of the BC project, and to help
provide feedback for the team implementing it. But right now, the BC
project is not active, and we don't know when or if it will restart. So I
don't think this is the time to adopt the beta table design.

I'm not sure where to go from here. Although I don't personally agree with
including all browsers in the WebExtension tables, I would go along with it
if the feedback from add-on developer was to do this. But the only feedback
I have had from the add-ons side (thanks Mindaugas!) is in favour of
including only browsers that have any support for WebExtensions, and that
tips me further in that direction.

Will

[Sebastian Zartner]

On 23 April 2016 at 01:21, William Bamberg <wbam...@mozilla.com> wrote:

> On Tue, Apr 19, 2016 at 11:44 PM, Sebastian Zartner <
> sebastia...@gmail.com> wrote:
>
>> In my opinion the compatibility tables should display the main browsers
>> everywhere by default (i.e. always have the same amount of columns like on
>> caniuse.com). The user may have the opportunity to (persistently)
>> customize the columns and display to his or her needs.
>>
>
>
> I feel as if customization is a bit of a red herring here. I don't have
> the ability to implement this (it would take platform support) and as we
> all know, defaults are powerful things, so even if it were possible,
> choosing optimal defaults would still be worth arguing over :).
>

I totally agree with you regarding the defaults.

> * they don't lend themselves to "aggregate" tables, like
>>> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/alarms#Browser_compatibility,
>>> because there isn't space for the name of the API on the same line as the
>>> row of green/red boxes
>>>
>>
>>
>> Yes, that's the cost of allowing to have more browsers listed. This could
>> be solved by putting them on the same line when there is enough horizontal
>> space, i.e. when only a few browsers are shown (but keep them on two lines
>> otherwise).
>>
>
>
> 'when only a few browsers are shown' - do you mean, by default show all
> browsers, but let the user exclude browsers, and if they exclude enough to
> fit the API name on the same line, then do so?
>

No to the first part of the sentence. By default we should show a sane
default, see above. Yes to the second part.

> But that means that by default, the aggregate table is not scannable. This
> just doesn't seem like a good experience.
>

By default the table would look like it does now, with the labels taking
their own lines.

Sebastian