Moving the WebExtensions docs


#1

On MDN we have docs for WebExtensions, the new cross-browser system for developing browser extensions. Currently these live at https://developer.mozilla.org/en-US/Add-ons/WebExtensions. This is in the “Add-ons zone”, and places the docs alongside docs that are clearly Mozilla-specific.

Actually, its real URL is https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/, so it’s explicitly in the “Mozilla” bit of the tree, but zones do some URL redirection for some reason.

We’ve recently decided to stop calling these things WebExtensions and start calling them just “Browser extensions”, which matches the name of the draft specification: https://browserext.github.io/browserext/.

We want to move the docs so the URLs match this name change. The current suggestion is to move them to https://developer.mozilla.org/en-US/Add-ons/Extensions, and there’s a PR already filed to update all the macros that hardcode the path: https://github.com/mdn/kumascript/pull/273.

But it’s also been suggested that we should move the docs from https://developer.mozilla.org/en-US/Add-ons/ (or more accurately, from https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/) out of the Mozilla-specific part of the tree, to reflect that this isn’t a Mozilla-specific technology, and to bring them more into the mainstream of the “MDN web docs”.

If we did this, then where should we move it to?

https://developer.mozilla.org/en-US/docs/Web/Extensions is one option, but it might confuse people into thinking that this technology is available to normal web pages

https://developer.mozilla.org/en-US/docs/Browser/Extensions is another, perhaps.

Or, we could just do the original move, into https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/. But I don’t really want to do that unless we are sure that’s a good long-term home.

I think whatever we do should have consensus from MDN leadership and add-ons leadership, as far as that’s possible. @atopal, @chrismills, @amyt, @amckay, that includes you.


[Support] FoxyLink
(YFdyh000) #2

LGFM.

Google Chrome looks don’t use “Add-ons” term.


(Elvin Lee) #3

Although WebExtensions as a framework is used by other browsers, my understanding is that they are not all the same. In particular, if Firefox’s WebExtensions has additional API support how will the Firefox-specific information be handled? Will that information still belong in the non-Mozilla part of the tree?


#4

As far as the reference docs are concerned, we would follow the same policy as for the open web docs: document everything in the non-Mozilla part of the tree, and use browser compat tables to indicate which browsers support an API. We already do this for:

… and so on.

As far as development workflow-type docs go, things are tricker because these things tend to be entirely browser-specific. Debugging, for example. In a perfect world, we’d have separate sections on workflow for each browser that supports the standard. Maybe we’ll get there one day. In the meantime, I’d suggest we have a separate section, in the non-Mozilla section of the tree, on Firefox workflow. In the current docs I have tried to corrall docs like that under a “Firefox workflow” section.


(Eric Shepherd) #5

This would be my preference. I know there’s not currently any other non-web cross-browser tech out there, really, but there could be eventually, and this sets us up for that. We can either have the page at docs/Browser express that, or we could for the time being made docs/Browser redirect to docs/Browser/Extensions until such time as it would be useful.

Sheppy


(Kadir Topal) #6

I’d vote for this structure. It makes it clear that this is something that’s not Mozilla specific, but at the same time not a part of the Web platform.


(amyt) #7

https://developer.mozilla.org/en-US/docs/Browser/Extensions looks fine to me. What do you propose doing with the add-ons landing page, since it’s one level above the Browser Extension page in the nav?

Also, puzzle piece would be great. Lmk if you need anything from us to do that.


#8

@amyt, I think the main add-ons landing page should stay where it is, since it links to a bunch of Firefoxy things, like AMO and the Mozilla lists. Even the part that links to extensions does so from a very Firefoxy place. It’s a natural place to send people who are looking to develop extensions for Firefox.


(amyt) #9

Sounds good, thanks!


(Andrew [:feer56] ) #10

Hi all,

I don’t think I see the change for this on MDN Web Docs yet, and I’m wondering if I could help tackle it by creating a new PR? Totally okay if there’s already something planned.

Cheers!


#11

Hi Andrew

No, this hasn’t happened yet. I was waiting a bit in case anyone else cared to chime in, but you’re right: it seems that we have consensus and should go ahead.

If you want to revive your original PR for the move, that’d be most welcome :slight_smile: .

In at least one way this is a bigger change than the original: the docs currently live in the “Add-ons zone” and that means they get certain custom CSS rules (for example, the colours in compat tables: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/browser_action#Browser_compatibility). So we’d need to enable the docs to get access to similar rules. This is totally doable though.

Actually I can’t think of any other ways in which this is different from the original proposal.

Will


(Chris Mills) #12

I know I’m late to this party, but just for the record, I also really like:

https://developer.mozilla.org/en-US/docs/Browser/Extensions

Makes it clear that it’s not a web technology, but instead is a (cross) browser technology, and also reflects the name of the API itself. The only thing that would be a pain is if they changed the name of the API again, but I think we are over that minefield now :wink:


(Andrew [:feer56] ) #13

I’ve dropped the ball on this, and I am unable to do what’s needed right now due to personal constraints.


#14

No worries Andrew :). I think we’ll need to schedule this work properly some time on Q4.


(Eric Shepherd) #15

Do we have an updated schedule for when the Browser Extensions docs will make their way to their new home at docs/Browser/Extensions?