Issue with "Browser Extensions": sub-documents not clear about limited availability of API

[randycasburn]

MDN URL: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions

What information was incorrect, unhelpful, or incomplete?

Related issues: mdn/browser-compat-data#8906 (comment)

Not incorrect exactly, but sub-documents require review in order to clarify the context of existence.

Specific section or headline?

All sub-documents related to "WebExtensions"

What did you expect to see?

When entering MDN from a search engine result, uses often access the sub-documents directly via a link on the search results page. When this occurs, the user is not clearly notified that the APIs documented here are for "WebExtensions" and will not work within the browser natively. This causes confusion unless the user happens to notice the crumb-trail mention of "Web Extensions" and actually knows what that means and how it relates to the content on the document.

It would be better if the each sub-document clearly stated near the top of the document that this API is meant for use with "Web Extensions" only.

For your consideration.

Did you test this? If so, how?

Search web for "windows.WindowState" navigate directly to the API sub-document. Try to determine that this API is only for use with WebExtensions.

MDN Content page report details

• Folder: en-us/mozilla/add-ons/webextensions
• MDN URL: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions
• GitHub URL: https://github.com/mdn/content/blob/master/files/en-us/mozilla/add-ons/webextensions/index.html
• Last commit: b3eebdd
• Document last modified: 2021-01-29T09:29:22.000Z

[rebloor]

@Rumyra – @mixedpuppy suggests that this probably falls within your bailiwick or for someone else who's working on MDN.

[Rumyra]

Thanks @rebloor - I wonder if we can address it within the strategy of add-ons -> web-extensions (which still needs planning)

[rebloor]

@Rumyra by the "strategy of add-ons -> web-extensions" I assume you effectively mean removing add-ons from the hierarchy, as highlighted with the oval below. I don't think that would address the reporter's concern. Their concern is that if you land on a web extensions API page, it's not clear that the API only applies to web extensions. I think they were looking for something more along the lines of the red box in the screenshot.

[randycasburn]

Yes. This was my original intent. Randy

…

On Oct 24, 2022, at 4:53 PM, rebloor ***@***.***> wrote: Their concern is that if you land on a web extensions API page, it's not clear that the API only applies to web extensions.

[Rumyra]

Sorry I'll elaborate:

We're currently implementing 'page-types' for MDN pages (see #15539). While web ext isn't in the first phase I envisage when we move these docs we can consider page types at the same time.

We can then use this page-type data to automatically add notes such as this to pages.

Another thing to note is we're working on a roadmap this quarter and that should help to define the time scale for this next year 👍

[rebloor]

@Josh-Cena what information do you have about activity on this one, e.g. why did you remove on-hold?

[Josh-Cena]

@rebloor There's no pending work that would block this from becoming reality—the WebExt docs already have page-types. Did you add on hold because the WebExt team thinks there's something else to be done first, or because you have no interest in doing it?

[rebloor]

@Josh-Cena I've flagged this as on hold because, according to my understanding, no decision has been made about whether such a note should be added to the API pages. @Rumyra has there been any further discussion on this?