967866 - Need a better 101 guide to start creating add-ons

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P1)

Description

[Will Bamberg [:wbamberg]]

We need a way for people new to add-on development to get started. The nearest thing we have right now is the combo of:

https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Installation
https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Getting_started_with_cfx

This has 2 problems:
* it's not easy enough to find from https://developer.mozilla.org/en-US/Add-ons/
* it's not written in a way that someone completely new to add-on development would find easy to follow

The plan would be to rewrite https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Getting_started_with_cfx to make it more clearly intro-to-addon-development type material, and then link to that prominently from https://developer.mozilla.org/en-US/Add-ons/. The new intro would still need to link back to "installation".

Some notes from IRC on this:

So there are two issues. One you can't really solve
which is the big step which exists to start creating add-ons
by having to install plenty of things, instead of starting hacking an extension
but the second part is about going through the step by step process of creating one
https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Getting_started_with_cfx
this requires already a lot of knowledge
> To create add-ons using the SDK you'll have to get to know the cfx command-line tool.
> It's what you'll use for testing and packaging add-ons.
it's already something for people with knowledge.
The vocabulary is not really for beginners
Basically, how would you refactor all this text, so that someone with almost no knowledge of all the tools and ecosystem, would learn
1. what the words mean
2. how to move forward one step at a time.

Comment 1

[Erik Vold [:erikvold] (please needinfo? me)]

So the current story around building your first add-on is pretty scary at the moment for someone that is unfamiliar with command line tools.  Perhaps we should write the ideal user story here and work towards making that a reality before writing an article like this.

Comment 2

[Will Bamberg [:wbamberg]]

Erik, it's true that the current situation with the SDK isn't ideal here and should be improved. And I think writing the ideal user story is a good idea too, although I thought that was already fleshed out somewhat with the JEP for the native add-ons work(?).

But I would prefer not to block improving the current docs on improving the SDK itself, especially with no very clear idea of when the SDK's story will improve here. It would be a different matter if I knew that the command line and need for transpilation would be going away in Firefox 30.

If we've reached the ideal situation with the SDK before I (or someone else) get around to addressing the issues captured in this bug, then I'll document the ideal situation instead.

Comment 3

[Jeff Griffiths (:canuckistani) (:⚡︎)]

This is awesome. I have two thoughts:

* we'll wait until the AOM / jpm stuff is usable, right?
* a new simpler intro tutorial would be a great page to link to from AMO

Comment 4

[Will Bamberg [:wbamberg]]

I've had a go at rewriting the "getting started" guide to be more beginner-friendly. Please let me know if this is what you had in mind: https://gist.github.com/wbamberg/9264998.

Comment 5

[Jeff Griffiths (:canuckistani) (:⚡︎)]

It looks fine, but as this will need to be re-worked again when we get jpm and the AOM changes landed, please don't put a lot of work into it now ( it doesn't look like you have, so just making sure ). +1 for making it into a single page though.

Comment 6

[Karl Dubost💡 :karlcow]

(In reply to Will Bamberg [:wbamberg] from comment #4)
> I've had a go at rewriting the "getting started" guide to be more
> beginner-friendly. Please let me know if this is what you had in mind:
> https://gist.github.com/wbamberg/9264998.

Thanks a lot Will. Yup this is much much simpler and useful.