canmove, Confirmed users
737
edits
JetpackWeb: Difference between revisions
→Current Structure
Canuckistani (talk | contribs) No edit summary |
|||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
__FORCETOC__ | __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. | |||