753072 - Add short documentation of quarantine problem on Mac OS X to README

Status: RESOLVED FIXED

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

Description

[Till Schneidereit [:till]]

+++ This bug was initially created as a clone of Bug #742063 +++

After just encountering this problem and only finding the solution through Stackoverflow, it occurs to me that the best place for a very short explanation would be the README file: That's almost guaranteed to be the place someone who's already on the command line will look first.

Comment 1

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

This probably won't be worked on anytime soon. Patches accepted, though! :)

Comment 2

[Till Schneidereit [:till]]

Taking so I don't forget about it, then :)

Comment 3

[Will Bamberg [:wbamberg]]

Thanks for taking this!

Just a suggestion: at the moment the README is really short. It's not obvious to me why we should document only this problem here, and not any of the other possible problems in https://addons.mozilla.org/en-US/developers/docs/sdk/latest/dev-guide/tutorials/troubleshooting.html? (which is where the documentation for this problem will live, in 1.7)

But if we copy all of that page into the README, it starts to get pretty long. So perhaps, instead of documenting this problem in the README, we could simply say something like "If you have any problems getting started, see the "Troubleshooting" guide at: https://addons.mozilla.org/en-US/developers/docs/sdk/latest/dev-guide/tutorials/troubleshooting.html"?

Comment 4

[Till Schneidereit [:till]]

That's a very good point. I'll take a closer look at the troubleshooting docs and see what makes sense.

I'm afraid that just generally saying "read the docs if you encounter a problem" won't actually make people, you know, read the docs ;)

My first idea is that maybe a sort of listing of symptoms in the README with the solutions explained in the full docs might be a good compromise.

Comment 5

[Till Schneidereit [:till]]

Attachment: Adds link to troubleshooting documentation to README

After looking at the troubleshooting doc ( and thinking some more ;) ), I think that listing symptoms probably will get old really fast.

Instead, I extended the proposed sentence to be a bit more specific about the kinds of problems (i.e., problems running stuff on the command line, not using the SDK in general).

Comment 6

[Will Bamberg [:wbamberg]]

Comment on attachment 622936 [details] [diff] [review]
Adds link to troubleshooting documentation to README

Looks great!

Comment 7

[[github robot]]

Commit pushed to master at https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/527a8d88dc44271a4a2af6c2d7fd6e7e4fc6c707
Bug 753072 - Add short documentation of quarantine problem on Mac OS X to README;r=@wbamberg