805234 - Create a README.md with links to important resources

Status: RESOLVED FIXED

(L20n :: JS Library, defect, P3)

Description

[Staś Małolepszy :stas]

A README.md with links to things like https://wiki.mozilla.org/L20n/Tracking and bug 800353 would be nice to have.

Comment 1

[Staś Małolepszy :stas]

I created a first version of the README file in https://github.com/l20n/l20n.js/commit/3aff9df039d24ff3905039d4d7c42571e92f2a9d

The file itself is https://github.com/l20n/l20n.js/blob/3aff9df039d24ff3905039d4d7c42571e92f2a9d/README.md.  The always-up-to-date version is also visible at https://github.com/l20n/l20n.js.

I'm landing this without asking Jeff for review because I'd like to have something live ASAP.  A lot of people asked for documentation about L20n after the talk at Front Trends.

Jeff, can you take a look at this next week and provide feedback?  Thanks!

Comment 2

[Staś Małolepszy :stas]

Some fixes landed overnight in https://github.com/l20n/l20n.js/commit/4ca5148fb133ba4a6e12057665bf85836a4ed65d

Thanks for the review, Jeff!  Two comments:

1. The README itself says that we're not doing pull request.  Instead, we attach patches to bugzilla.  This is really important for me from the code history point of view.  All code discussion should be in Bugzilla.

2. I'm not sure the following edit is correct:

-compiled.  Register callbacks to execute when the context is ready, or listen 
+compiled.  Register calls back to execute when the context is ready, or register calls back to listen  

A 'callback' is a widely-used term for a function that is called when something finishes (usually successfully).  There are also 'errback', i.e. function to call when things go wrong.

Comment 3

[Jeff Beatty [:gueroJeff]]

(In reply to Staś Małolepszy :stas (needinfo along with cc, please; if you want an r+ from me, attach your patch to the bug; I don't review pull requests) from comment #2)
> Some fixes landed overnight in
> https://github.com/l20n/l20n.js/commit/
> 4ca5148fb133ba4a6e12057665bf85836a4ed65d
> 
> Thanks for the review, Jeff!  Two comments:
> 
> 1. The README itself says that we're not doing pull request.  Instead, we
> attach patches to bugzilla.  This is really important for me from the code
> history point of view.  All code discussion should be in Bugzilla.
> 
> 2. I'm not sure the following edit is correct:
> 
> -compiled.  Register callbacks to execute when the context is ready, or
> listen 
> +compiled.  Register calls back to execute when the context is ready, or
> register calls back to listen  
> 
> A 'callback' is a widely-used term for a function that is called when
> something finishes (usually successfully).  There are also 'errback', i.e.
> function to call when things go wrong.
Thanks Stas!

I understand your concern. When used as a noun, yes, it remain unbroken. But as a verb, I've only ever heard "calls back" to refer to the function you mention here.

Comment 4

[Staś Małolepszy :stas]

(In reply to jbeatty from comment #3)
> > A 'callback' is a widely-used term for a function that is called when
> > something finishes (usually successfully).  There are also 'errback', i.e.
> > function to call when things go wrong.
> Thanks Stas!
> 
> I understand your concern. When used as a noun, yes, it remain unbroken. But
> as a verb, I've only ever heard "calls back" to refer to the function you
> mention here.

I still think this is wrong, and I think the problem is in "register" and "listen", not callback.  In that sentence, callback was intended to be a noun.  It's not "[The] register [does what?] calls back" but instead: [imperative, you] register [what?] callbacks.  Does it make sense?  Maybe it needs to read "Register the callbacks"?  (Articles are hard...)

How can we improve this sentence to avoid this confusion?

Respectfully reopening :)

Comment 5

[Jeff Beatty [:gueroJeff]]

(In reply to Staś Małolepszy :stas (needinfo along with cc, please) from comment #2)
> Some fixes landed overnight in
> https://github.com/l20n/l20n.js/commit/
> 4ca5148fb133ba4a6e12057665bf85836a4ed65d
> 
> Thanks for the review, Jeff!  Two comments:
> 
> 1. The README itself says that we're not doing pull request.  Instead, we
> attach patches to bugzilla.  This is really important for me from the code
> history point of view.  All code discussion should be in Bugzilla.
Ah man! This makes things more complicated for me here. I don't know how to create patches using git, only hg.
> 
> 2. I'm not sure the following edit is correct:
> 
> -compiled.  Register callbacks to execute when the context is ready, or
> listen 
> +compiled.  Register calls back to execute when the context is ready, or
> register calls back to listen  
> 
> A 'callback' is a widely-used term for a function that is called when
> something finishes (usually successfully).  There are also 'errback', i.e.
> function to call when things go wrong.

You're explanation in Comment 4 makes perfect sense. The absence of the article made it seem like "callbacks" was being used as a verb and not a noun. How about this instead?

"The register callbacks will execute when the context is ready, or they will listen to the `LocalizationReady` event emitted by `document.l10n`."

Comment 6

[Staś Małolepszy :stas]

Oh man, this is hard :)  They're not register callbacks;  you are registering callbacks which will execute or you are listening (with some other code) to events.

Creating patches with git is very similar to hg.  See https://developer.mozilla.org/en-US/docs/L20n/Contribute :)

Comment 7

[Jeff Beatty [:gueroJeff]]

(In reply to Staś Małolepszy :stas (needinfo along with cc, please) from comment #6)
> Oh man, this is hard :)  They're not register callbacks;  you are
> registering callbacks which will execute or you are listening (with some
> other code) to events.
> 
> Creating patches with git is very similar to hg.  See
> https://developer.mozilla.org/en-US/docs/L20n/Contribute :)

Sorry, it's not that hard, you explained it perfectly in your last comment. You're just talking to a jetlagged idiot right now. After re-reading it, I think it was the sentence order that confused me the first time. Third time's a charm, right?

"When the context is ready, either register callbacks for execution or listen to the `LocalizationReady` event emitted by `document.l10n`."

How's that?

Comment 8

[Staś Małolepszy :stas]

Perfect, I'll change it :)  Thank you.

Comment 9

[Staś Małolepszy :stas]

I reworded the whole paragraph in the end, like so: https://github.com/l20n/l20n.js/commit/1940ce82ff75503ba3cbb4f7fec3f5835000894d

Comment 10

[Jeff Beatty [:gueroJeff]]

(In reply to Staś Małolepszy :stas (needinfo along with cc, please) from comment #9)
> I reworded the whole paragraph in the end, like so:
> https://github.com/l20n/l20n.js/commit/
> 1940ce82ff75503ba3cbb4f7fec3f5835000894d

Looks great to me. Sorry for the confusion.