916353 - Rename Learn chapters by usecase

Status: RESOLVED FIXED

(L20n :: Evangelism, defect, P1)

Description

[Staś Małolepszy :stas]

Currently the Learn chapters are named by L20n's features, which don't mean much to people not familiar with L20n.

Hopefully, we can keep most of the present content and structure and just find better-suited names for the chapters.

Comment 1

[Matjaz Horvat [:mathjazz]]

Here's the list of new chapter names:
https://l20n.etherpad.mozilla.org/byexample

Comment 2

[Jeff Beatty [:gueroJeff]]

The names including the term "variants" are too general. Is there a more descriptive term than variant? I also prefer "Gender" or "localizing genders" or something like that. I feel like the chapter titles still use a lot of developer terms that don't describe the use case. However, at the moment, I can't think of better ones. Perhaps it's because I'm seeing the titles out of context and am thus having a difficult time deciphering meaning from them alone.

Comment 3

[Staś Małolepszy :stas]

I updated my suggestions in the etherpad and I'm pasting them here as well:

 0. Introduction
 1. Hello World
 2. Working with text: multiline, interpolation
 3. Translations with multiple variants
 4. Defining the default variant
 5. Choosing one variant
 6. Using variants to define grammatical cases       // previously: "declensions"
 7. Using external variables in translations
 8. Making translations depend on external variables
 9. Describing translations with custom data
10. Making translations depend on custom data        // previously: "genders"
11. Plural forms (introduction to macros)
12. Building macros and expressions
13. Adapting translations to current time
14. Adapting translations to user's operating system
15. Adapting translations to screen size
16. Don't repeat yourself: helper entities
 x  Helper attributes                                // remove, already covered by #8
17. Putting it all together: Complex plurals example

Comment 4

[Staś Małolepszy :stas]

(In reply to Staś Małolepszy :stas from comment #3)
>  x  Helper attributes                             // remove, already covered by #8

This should read: #9.

Comment 5

[Matjaz Horvat [:mathjazz]]

Thanks, Stas!

I'd prefer shorter titles, which could be done by removing general terms like "translations" and "using" (that suit any chapter name), and focusing on keywords. E.g., the title "Translations with multiple variants" doesn't tell much more than just "Multiple variants". Both of them are equally cryptic. ;)

But I think we talked about this way too much already, so let's ship it. ;)

Comment 6

[Jeff Beatty [:gueroJeff]]

(In reply to Staś Małolepszy :stas from comment #3)
> I updated my suggestions in the etherpad and I'm pasting them here as well:
> 
>  0. Introduction
>  1. Hello World
>  2. Working with text: multiline, interpolation
>  3. Translations with multiple variants
>  4. Defining the default variant
>  5. Choosing one variant
>  6. Using variants to define grammatical cases       // previously:
> "declensions"
>  7. Using external variables in translations
>  8. Making translations depend on external variables
>  9. Describing translations with custom data
> 10. Making translations depend on custom data        // previously: "genders"
> 11. Plural forms (introduction to macros)
> 12. Building macros and expressions
> 13. Adapting translations to current time
> 14. Adapting translations to user's operating system
> 15. Adapting translations to screen size
> 16. Don't repeat yourself: helper entities
>  x  Helper attributes                                // remove, already
> covered by #8
> 17. Putting it all together: Complex plurals example

So much better! Great ideas, Stas!

Comment 7

[Staś Małolepszy :stas]

(In reply to Matjaz Horvat [:mathjazz] from comment #5)
> Thanks, Stas!
> 
> I'd prefer shorter titles, which could be done by removing general terms
> like "translations" and "using" (that suit any chapter name), and focusing
> on keywords. E.g., the title "Translations with multiple variants" doesn't
> tell much more than just "Multiple variants". Both of them are equally
> cryptic. ;)
> 
> But I think we talked about this way too much already, so let's ship it. ;)

Matjaž, you have a point.  These words seem a bit redundant, but it was my conscious decision to use a verb in each title.  It's telling that you mentioned "Translations with multiple variants" because that's one of the few title without any verbs (the other one being "Plural forms").  I also considered:  "Branching translations", "Defining multiple variants/values of translations", "Defining many translations for one message" among other.  Do any of these sound better to you?

I think I'd still prefer to keep "translations", as we use a lot of jargon all over the place:  variants, variables, data, macros etc.   I feel it helps to be a bit more precise (and descriptive) and use the term "translations" when needed.

Comment 8

[Jeff Beatty [:gueroJeff]]

(In reply to Staś Małolepszy :stas from comment #7)
> (In reply to Matjaz Horvat [:mathjazz] from comment #5)
> > Thanks, Stas!
> > 
> > I'd prefer shorter titles, which could be done by removing general terms
> > like "translations" and "using" (that suit any chapter name), and focusing
> > on keywords. E.g., the title "Translations with multiple variants" doesn't
> > tell much more than just "Multiple variants". Both of them are equally
> > cryptic. ;)
> > 
> > But I think we talked about this way too much already, so let's ship it. ;)
> 
> Matjaž, you have a point.  These words seem a bit redundant, but it was my
> conscious decision to use a verb in each title.  It's telling that you
> mentioned "Translations with multiple variants" because that's one of the
> few title without any verbs (the other one being "Plural forms").  I also
> considered:  "Branching translations", "Defining multiple variants/values of
> translations", "Defining many translations for one message" among other.  Do
> any of these sound better to you?
> 
> I think I'd still prefer to keep "translations", as we use a lot of jargon
> all over the place:  variants, variables, data, macros etc.   I feel it
> helps to be a bit more precise (and descriptive) and use the term
> "translations" when needed.

I like "Branching translations" the best. Nevermind, I LOVE "Branching translations" :-D

Comment 9

[Staś Małolepszy :stas]

(In reply to jbeatty from comment #8)

> I like "Branching translations" the best. Nevermind, I LOVE "Branching
> translations" :-D

So much is lost in the written form:  I cannot tell if you're being facetious or not. Sorry.

Another idea I had:  "Defining multiple variants of one translation".

Comment 10

[Matjaz Horvat [:mathjazz]]

(In reply to Staś Małolepszy :stas from comment #7)
> 
> I think I'd still prefer to keep "translations", as we use a lot of jargon
> all over the place:  variants, variables, data, macros etc.   I feel it
> helps to be a bit more precise (and descriptive) and use the term
> "translations" when needed.

I most definitely agree that the titles are now more descriptive, my only concern was increased amount of space needed. But I'm afraid they come together in the same package, so we can't do much about it.

I used "variants" instead of "branching", because we use this word in the chapter several times:
http://l20n.org/learn/dictionary-values/

So if we switch to "branching", we might consider using this word in the chapter content as well. But I'm taking a wild guess here - my experience with copywriting in English is more or less non-existent. ;)

Comment 11

[Matjaz Horvat [:mathjazz]]

Attachment: New chapter names

Comment 12

[Jeff Beatty [:gueroJeff]]

Comment on attachment 823438 [details] [diff] [review]
New chapter names

I don't like this patch, but I understand that you've updated it with what I do like, so I'm flagging this patch as an r- but will approve the other :-)

Comment 13

[Matjaz Horvat [:mathjazz]]

Attachment: New chapters 2.0

Comment 14

[Staś Małolepszy :stas]

Comment on attachment 823530 [details] [diff] [review]
New chapters 2.0

Thanks, Matjaz, for putting together the final list.  r=me.

Re. branching, I'll leave it up to Jeff to make the call.  I like variants, but I biased (variants is what works in Polish)

> 3. Translations with multiple variants
> 4. Defining the default variant
> 5. Choosing one variant
> 6. Using variants to define grammatical cases

These could be rephrased as follows:

> 3. Branching translations
> 4. Defining the default branch
> 5. Choosing a specific branch
> 6. Using branches to define grammatical cases

How does that sound?

Comment 15

[Matjaz Horvat [:mathjazz]]

Thanks, Stas!

I also prefer variants to branches. The word "branch" has unfortunate connotations when talking about translations; it could be easily misunderstood that we're dealing with repositories.

Comment 16

[Jeff Beatty [:gueroJeff]]

(In reply to Matjaz Horvat [:mathjazz] from comment #15)
> Thanks, Stas!
> 
> I also prefer variants to branches. The word "branch" has unfortunate
> connotations when talking about translations; it could be easily
> misunderstood that we're dealing with repositories.

I understand the concern with "branching." "Variant" sounds so niche and vague, but I can't think of a better term to replace it with. "Variant" wins! 

PS, did you know that "translation" is a synonym of "variant?" http://thesaurus.com/browse/variant?page=2

Comment 17

[Matjaz Horvat [:mathjazz]]

Thank you, guys!

This is now fixed:
https://github.com/l20n/l20n.org/commit/004a58efe888da9a24012b348ddff63240082a40