MDN/Plans/2016/Add-ons

From MozillaWiki
< MDN‎ | Plans‎ | 2016
Jump to: navigation, search

This is a plan for what to do about the Add-on docs on MDN in Q1 2016.

It's structured like this:

  • the first major section covers what the Add-on docs on MDN should contain, and what the current problems are.
  • the second section consists of three parts, and outlines what we should do about:
    • existing content
    • the landing page
    • new content

Intro

What the Add-on docs are

The Add-on docs on MDN should explain to developers how to write and publish add-ons for any platforms which we commit to supporting. The docs should include:

  • how to get started
  • development workflow and tools: how to package, install, test, and debug add-ons
  • distribution: how to get add-ons into the hands of users
  • in-depth guides on technical aspects of add-on development
  • API reference material
  • examples

What's wrong with the Add-on docs?

Historically we've supported:

  • multiple sorts of add-ons: plugins, extensions, themes..
  • on several different platforms: Firefox, SeaMonkey, Thunderbird...
  • some of which can use several different technology stacks: XUL overlay, bootstrapped extensions, SDK, Fennec APIs

This results in a complex and confusing landscape for add-on developers. We've been more committed to some of these things than to others, both in terms of the technology and in terms of the docs. Many of the docs for some of these things are therefore not well maintained and less than useful. It's hard for add-on developers to get a clear message about what they can do with add-ons, which platforms they can target, and which technology stacks they should use.

We've recently committed to:

  • developing WebExtensions as the primary "golden path" for add-on developers on Firefox Desktop and, in future, Firefox for Android
  • deprecating, and eventually withdrawing support for, XUL and XPCOM access from add-ons
  • deprecating certain low-level Add-on SDK APIs.

Additionally:

  • plugins are deprecated
  • it's not clear whether we will continue to support add-ons for other platforms, like Thunderbird or SeaMonkey.

These changes considerably simplify the landscape, and the docs should be revised to reflect this, and to give add-on developers a clear message.

The Plan

The main points are these:

  • dealing with XUL/XPCOM deprecation: docs that describe technologies or techniques that depend on XUL or XPCOM technologies, should be either deprecated (if they are only applicable to add-ons) or marked internal and moved (if they are still applicable to internal Firefox code)
  • dealing with unmaintained docs that are no longer useful: docs that describe other technologies or platforms that we no longer plan to support, or that are so out of date as to be not useful, should be either deprecated or archived. We archive docs if they should no longer be used.
  • providing useful guidance to people trying to develop add-ons for Firefox/Firefox for Android: based on this cleanup, give people clear and helpful choices.

There are three pieces to this:

  1. fixing existing content: going through the pages in the Add-ons zone and deciding what to do with them. The choice, for each page, is essentially:
    • keep unchanged
    • move: out of the Add-ons zone, or to a better spot in the Add-ons zone
    • deprecate: add a deprecation notice at the top of the page, recommending that people don't use this any more
    • mark internal: add a notice at the top of the page, saying that this is intended to be only an internal Firefox technology in future.
    • archive: move the docs to the archive. We should only do this if we don't expect the docs to be useful to anyone any more.
  2. fixing the landing page: redesigning the main page (and sidebar) to give clear up to date guidance.
  3. writing new content: adding things that are missing.

Fixing existing content

We currently have about 577 pages under https://developer.mozilla.org/Add-ons. (doc list).

Breaking this down by hierarchy, we get:


That leaves 31 docs that are at the top level (plus two that are single-children of a top-level doc, so not worth calling out as a hierarchy):

Let's go through each of these groups.

AMO

These docs are still applicable, and are in reasonable shape. We can just leave them here. But we should probably create a new hierarchy under the Add-ons root, called "Publishing", or something, that might leave better room for non-AMO aspects of add-on distribution.

Add-on Manager

These docs describe an XPCOM-dependent technology, that could still be useful to internal Firefox code.

=> mark as internal, move out of the Add-ons tree.

Code snippets

These docs describe an XPCOM-dependent technology, that could still be useful to internal Firefox code.

=> mark as internal, move out of the Add-ons tree.

Firefox for Android

These docs are tricky. They are properly maintained, mobile add-ons are a differentiator for us, and we don't currently provide any alternatives to the current technology.

However, Fennec add-ons are XPCOM-dependent, so some of this technology will change in the future. But it's not yet clear when, or exactly what the replacement would look like (other than, a flavour of Web Extensions).

=> keep these docs, as the primary way to develop for Fennec. But indicate that aspects of Fennec add-on development are likely to change in the future, as XPCOM deprecation happens, and that the replacement is expected to be Web Extension-flavoured.

Legacy extensions

These are guides for developing XUL overlay add-ons.

=> deprecate

Plugins

Reference information for plugin developers.

=> deprecate

SDK

=> deprecate the modules that we know we will deprecate. Start a conversation about which other ones need to be deprecated. Once we know, deprecate those extra ones, and amalgamate "high level" and "low level" APIs.

=> deprecate any other guides that are XPCOM-dependent.

Themes

This contains 2 pages on lightweight themes, and a few more on complete themes. The complete theme documentation is very out of date.

=> I'm tempted to archive the complete theme docs here.

Note, though, there is a page on themes that is outside the Add-ons zone: https://developer.mozilla.org/en-US/docs/Building_a_Theme, that looks a bit more current. Perhaps we should move this doc under Add-ons, and deprecate it?

Thunderbird

Very old docs on Thunderbird extensions.

=> archive. I don't think these docs are useful as they stand.

WebExtensions

=> keep, obviously.

Remnants

The following top-level docs should be moved under Legacy extensions and deprecated:

Going through the others one by one:

Fixing the landing page

  • remove the distinction between "add-ons" and "extensions". Treat extensions as just add-ons. Have a section further down the page "Other types of add-on" where we can mention themes and plugins.
  • give WebExtensions and SDK add-ons equal billing for now. Have prominent links to "Getting started" for both technologies. Indicate that WebExtensions will be the best option in future, but that they are not there yet.

After that, have the following major sections:

  • Mobile: that presents the Fennec APIs as the best approach right now, but notes that they include technologies that will be deprecated in future, and that in the future, Web Extensions will support Firefox for Android.
  • Publishing:
  • Legacy add-ons: that calls out overlay and bootstrapped add-ons as legacy technology. It also needs to link prominently to the article on dealing with e10s.
  • Other types of add-on:
    • Themes: link to Lightweight themes. Complete themes are deprecated (just mention, don't link?)
    • Search engine plugins
    • Plugins: deprecated

Note that we're omitting any links to non-Firefox add-on development (Thunderbird, SeaMonkey).

New content

All the new content listed here is for WebExtensions. This list is not meant to be exhaustive: this is just what's currently planned.

  • API reference docs: we will generate the initial set of these from the JSON files in Chromium. We're ready to do this, but blocked on an MDN platform bug. We'll subsequently update the content manually, and this will be an ongoing job.
  • Examples: we'll have examples for at least all the WebExtension APIs, and preferably several, illustrating all the major things you can do with them. We'll have macros that can automatically link from API reference pages relevant examples.
  • Guides: many of the basic guides are written. We still need, at least:
    • Detailed workflow guide of how to get set up, develop, debug, publish
    • Messaging
    • i18n
    • Security
    • UX
Retrieved from "https://wiki.mozilla.org/index.php?title=MDN/Plans/2016/Add-ons&oldid=1112612"