Closed Bug 661303 Opened 10 years ago Closed 10 years ago

Create FAQ for the Add-on SDK 1.0 release

Categories

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

defect

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: dcm, Assigned: wbamberg)

References

Details

Attachments

(1 file)

We need a FAQ for the Add-on SDK 1.0 release.
dcm tells me Will is tackling this one.

Will: note the existing FAQ at https://jetpack.mozillalabs.com/faq.html.
Assignee: nobody → wbamberg
Depends on: 660286
OS: Mac OS X → All
Priority: -- → P1
Hardware: x86 → All
Target Milestone: --- → 1.0
I've taken the spreadsheet at 
https://spreadsheets.google.com/spreadsheet/ccc?hl=en_US&key=trtZkd33F6W9s2IdHa1pdQw&hl=en_US#gid=0 and posted it into the Wiki at:
https://wiki.mozilla.org/Labs/Jetpack/FAQ.

It's comprised mostly of Myk's FAQ from the Labs page, plus a selection of programming questions that have come up on the list or IRC.

Before having a detailed review of the answers, I'd like to know whether this is what you'd like to see as the FAQ: whether these are the right sorts of questions, whether there are too many or too few.

Also, I suppose, whether you think the Wiki is an appropriate place for the FAQ - it's easy enough to relocate it if not, but I thought having it there made it fairly easy to review.

Thanks!
Attachment #537058 - Flags: feedback?(dcm)
Thanks Will, this is great. This is precisely what we needed from our end. From what I understand, PR will likely have comments on it. 

I think having it on a wiki is perfect - at some point we probably want to move (or more likely recreate) our wiki somewhere off of Labs - but its not a 1.0 blocker by any means.
"can the add-on sdk do everything that XUL add-ons can do? can i rewrite my XUL add-on today?"

variations on this same question come up often. experienced XUL add-on devs get frustrated and disappointed. we should communicate clearly which developers and what types of add-ons we're targeting 1.0 at.
Blocks: 660286
No longer depends on: 660286
Comment on attachment 537058 [details]
Link to FAQ in the Wiki

So I think this is reasonable enough to ask for some detailed feedback on the content, although there are a few things I'm not too happy about. 

* The sections, and section names. I think sections are useful, but I'm not sure "General" or "General Programming" are any good.

* The "Building a UI" section seems to consist largely of saying "no, you can't do that" and as such isn't very positive. But these are important questions people ask.
Attachment #537058 - Flags: review?(myk)
(In reply to comment #4)
> "can the add-on sdk do everything that XUL add-ons can do? can i rewrite my
> XUL add-on today?"
> 
> variations on this same question come up often. experienced XUL add-on devs
> get frustrated and disappointed. we should communicate clearly which
> developers and what types of add-ons we're targeting 1.0 at.

Thanks Dietrich. I had a go at answering this, but if you've got comments on that I'd like to hear them.
Comment on attachment 537058 [details]
Link to FAQ in the Wiki

> Can I do everything with the Add-on SDK that I could with a XUL-based add-on? Should I rewrite my XUL-based add-on now?

There are two issues with this section.

First, it says that you can't do everything with an SDK-based addon that you can do with a XUL-based addon, but you actually can do (substantially?) everything, including modifying XUL windows, accessing XPCOM components, and loading your own XPCOM components, both binary and JS.

You just have to do some things differently (f.e. DOM manipulation instead of XUL overlays), and, as the section notes, the SDK is currently targeted primarily at web developers who are new to addon development, so we haven't yet designed and developed the right set of functionality for existing addon developers building advanced addons.

Second, the section doesn't mention that one of our top priorities for the second half of the year is to help developers migrate from the traditional platform to the new one.

So I would make this section a bit more nuanced and say that 1. you actually can do (substantially?) everything, 2. the SDK is not yet targeted to advanced developers, 3. we intend to help XUL addon developers transition to the SDK in the second half of the year, and 4. if you're a XUL addon developer who is an early adopter and willing to participate in the development process, now is the right time to try out the SDK and help us figure out the right set of features to enable you to make the transition.


Python 2.6 or 2.6 -> Python 2.5 or 2.6

(I think 2.7 works too, although I'm not sure if we've tested enough to officially support it; requesting feedback from Brian on this.)


"Why doesn't window.alert() work in my add-on?" should mention that console.log is the preferred alternative to window.alert() for debugging purposes.


> var pageMod = require(""page-mod""); 

Here and elsewhere, "" -> "


Nit: How can i read from/write to a file? -> How can I read from/write to a file?
Attachment #537058 - Flags: review?(myk)
Attachment #537058 - Flags: review-
Attachment #537058 - Flags: feedback?(warner-bugzilla)
Comment on attachment 537058 [details]
Link to FAQ in the Wiki

python2.7 seems to work fine, I just did some quick smoke-tests on OS-X and everything seems ok. We don't have any automated coverage, but if any py2.7-specific problems show up, I'll jump on them quickly, so I'd call it "supported".

OTOH, it's not that widely deployed (I think 2.6 is most common), and nobody with py2.7 will look at a "requires python 2.5 or 2.6" note in the docs and run away without at least giving it a try (and being pleasantly surprised to see it work), so I'm equally happy with the docs only mentioning 2.5/2.6 .
Attachment #537058 - Flags: feedback?(warner-bugzilla) → feedback+
Comment on attachment 537058 [details]
Link to FAQ in the Wiki

Updated the FAQ.
Attachment #537058 - Flags: review?(myk)
Attachment #537058 - Flags: review-
Attachment #537058 - Flags: feedback?(dcm)
Comment on attachment 537058 [details]
Link to FAQ in the Wiki

Groovy!
Attachment #537058 - Flags: review?(myk) → review+
Status: NEW → RESOLVED
Closed: 10 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.