View source for Jetpack/Web Presence/AMO MDN Dev Doc

__FORCETOC__

This document proposes a restructuring of parts of the AMO and MDN web sites to make it easier for add-on developers to find the information they are looking for.

== Current Structure ==

The diagram below shows the parts of the AMO and MDN web sites that add-on developers looking for documentation must navigate. I’ve highlighted the pages that contain actual developer documentation:

[[File:Jetpack_web_presence_proposed.png]]

There are a couple of problems with this structure:

=== Problem 1 ===
Long navigation path: add-on developers are looking for concrete documentation of the tools Mozilla provides. We can test how good a time they have by how quickly they can get there from the [https://developer.mozilla.org/en MDN] or [https://addons.mozilla.org/en-US/firefox/ AMO] home pages. Here, from the home pages, they have to go through two landing pages before they get to any developer documentation for the SDK:

* in the AMO case, they must go to the [https://addons.mozilla.org/en-US/developers/ Developer Hub], then the [https://addons.mozilla.org/en-US/developers/builder SDK/Builder landing page], then find the link to the docs.
* in the MDN case, they must either:
** find the “[https://developer.mozilla.org/en-US/docs More Docs]” link on the main page, then go through the “[https://developer.mozilla.org/en-US/addons Add-ons Developer Community]” page, then the [https://addons.mozilla.org/en-US/developers/builder SDK/Builder landing page], then find the link to the docs.
** go from the main page, to the [https://addons.mozilla.org/en-US/developers/ Developer Hub], to the [https://addons.mozilla.org/en-US/developers/builder SDK/Builder] page, to the docs.

(actually, there’s another link from the MDN home page labeled “Developing add-ons” that goes to a [https://developer.mozilla.org/En/Developing_add-ons quite old-looking page]. That needs fixing too.)

Additionally, the links to the technical content aren’t obvious - especially, the link from the SDK/Builder page to the documentation is non-obvious (the link to download the SDK is much more prominent, but new developers are likely to want to read about the SDK before downloading it).

Here’s some developer feedback on their experience trying to find the SDK docs: [https://forums.mozilla.org/addons/viewtopic.php?f=27&t=4664 https://forums.mozilla.org/addons/viewtopic.php?f=27&t=4664].

Note that it’s just as bad for XUL devs, this isn’t a Builder/SDK-specific problem.

=== Problem 2===
No clear distinction between Builder/SDK/XUL toolsets. Currently Mozilla offers three distinct toolsets for developing add-ons: the Builder, the SDK, and the XUL. Choosing a toolset is the first decision a developer needs to make.

But the “[https://addons.mozilla.org/en-US/developers/ Developer Hub]” page on AMO, and the “[https://developer.mozilla.org/en-US/addons Add-ons Developer Community]” pages are problematic because they don’t present this. They’re actually very similar pages: both have a prominent link to the SDK/Builder, followed by links called things like “API Reference” and Tutorials” - that then link only to XUL tutorials. This is confusing for developers!

It would be better to explain in these pages that there are three toolsets, and help a developer choose a path. Then once they’ve chosen a path, present API reference and tutorials relevant to that path.

== Proposed New Structure ==
In the proposed new structure we’ve tried to:

* simplify things, remove redundancy, and shorten the path for developers looking for concrete technical info
* present developers, early on, with the choice of toolset, and given them the information they need to make the right choice. Subsequently, they only see information relevant to that choice.

[[File:Jetpack_web_presence_current.png]]

From both the AMO and the MDN main page, a fairly prominent link called “Developing Add-ons” or “Developer Hub” or something like that goes to a new page, hosted at MDN - we’ve kept the name “Add-ons Developer Community” here, but it doesn’t have to be called that.

This page explains that there are these 3 toolsets, and explains concisely by comparison why you might want to choose one rather than another. It then links to each toolset:

* the Builder link goes to the [https://builder.addons.mozilla.org/ Builder]
* the SDK link goes to the [https://addons.mozilla.org/en-US/developers/docs/sdk/latest/ SDK docs]
* the XUL link goes to a new page that collects the links currently under the Developer Hub page, like [https://addons.mozilla.org/en-US/developers/docs/reference API Reference], [https://addons.mozilla.org/en-US/developers/docs/how-to How-Tos], and so on (note that these sub-pages are currently hosted on AMO: since the actual content is all on MDN it might make sense to move them to MDN too, as the diagram shows). We’ll need help writing this page.

== Other Stuff ==
Other stuff we talked about, that’s not strictly relevant here, but is important:

* the Jetpack Wiki: we decided to:
** de-uglify it as much as possible
** move some stuff, like FAQ, to MDN when the SDK docs move there

* the SDK docs should be more Builder-friendly. Maybe this is just a matter of highlighting stuff that’s SDK-specific, and describing the alternative Builder-based technique.