Target audiences for l20n doc

[Jeff Beatty]

Hey guys,

I'm outlining the target audiences for the MDN L20n doc and having some
difficulty really evaluating the differences between target audiences
and the information to present to each. Here's how I see it:

Target audiences:
- Localizer
-Localizer with coding knowledge
-Localizer with linguistics knowledge
- The localizer has a solid understanding of the linguistic
constructs within their language that make it unique and a challenge to
translate into. The localizer may have some coding experience, but
ultimately understands how the current frameworks for translating
strings impede their ability to be fully expressive.

-Developer
- Web developer
- i18n/l10n engineer
- The developer is interested in enabling multilingual content
within their application/website. They understand the principles of i18n
on the web and the challenges involved in providing a truly
language-independent framework for localization. They also understand
the complexities of language and the challenges associated with
displaying/processesing various languages on a computer.

-Product manager
- The PM is interested in evaluating L20n's ability to provide
a comprehensive framework for accurate localization within a short
timeframe. The PM understands some principles of i18n and l10n, but
ultimately cares about it's interoperability within the organization's
current tool chain and within existing l10n industry standards.

Based on these descriptions, it seems that developers would need to
learn how to enable L20n and what sort of L20n code they might
encounter. They also need to understand how the .lol file type will
interact within their own code. PM's would be interested in the above
information, as well as some performance related data and white pages on
how L20n ultimately improved a localized product and the process by
which it was localized. Localizers would need to learn the principles,
syntax, and use of L20n, ultimately aiming toward teaching them how to
successfully code in L20n for their language.

I, personally, think that there should be a cheatsheet, but I don't
think there needs to be one per audience.

Have I hit everything? Is there anything I've missed? Would you agree
with the assessment of the target audiences for the L20n doc?

Thanks,
Jeff


--
*Jeff Beatty*
L10n Program Manager
@mozilla_l10n <http://twitter.com/mozilla_l10n>
801.367.3763

[Jeff Beatty]

El 5/24/13 7:34 a.m., Matjaz Horvat escribió:
> I think l20n in general has two audiences: localizers and developers.
I certainly agree, but if we want wide adoption, we also have to aim
some documentation at a management audience. Developers don't always
make technical requirement decisions, unless they're working on their own.
>
> Localizers want to know how to localize and their docs is available at
> http://l20n.org/learn/.
That's a nice, practical tutorial for learning about what l20n is
capable of, but localizers will also need reference materials including
a "cheatsheet" for quick reference if they hope to really learn how to
code in l20n and localize strings within l20n code. If L20n by example
could be expanded to include these reference docs, that would be great,
but I think that's outside the scope and more appropriate for MDN.
>
> Developers want to know how to make their app localizable and their
> docs should be on MDN.
>
Agreed.
> I don't think we should care about other audiences at this stage.
Perhaps the PM audience's needs could also be addressed by L20n.org and
L20n by example and we wouldn't need to add anything new that is
specific to them. I could see that being the case too.
>
> -Matjaz
>
> Sent from my iPad
>
> On 23. maj 2013, at 18:30, Jeff Beatty <jbe...@mozilla.com

>> _______________________________________________
>> tools-l10n mailing list
>> tools...@lists.mozilla.org <mailto:tools...@lists.mozilla.org>
>> https://lists.mozilla.org/listinfo/tools-l10n

[Staś Małolepszy]

Quoting Jeff Beatty (2013-05-23 18:30:55)

> Hey guys,
>
> I'm outlining the target audiences for the MDN L20n doc and having some
> difficulty really evaluating the differences between target audiences
> and the information to present to each. Here's how I see it:
>
> Target audiences:
> - Localizer
> -Localizer with coding knowledge
> -Localizer with linguistics knowledge
> - The localizer has a solid understanding of the linguistic
> constructs within their language that make it unique and a challenge to
> translate into. The localizer may have some coding experience, but
> ultimately understands how the current frameworks for translating
> strings impede their ability to be fully expressive.

The localizer might be interested in three resources that I had in
mind:

- a 30-minute walkthrough, lesson by lesson. This is essentially what
/learn aspires to be, but we should make it a little bit more
localizer-friendly (e.g. by renaming the chapters). This would also
be used as a reference that the localizer can come back to (e.g.,
'How do I call a macro?', or 'How do I make an entity depend on
a variable passed in by the developer?')

- a repository of common use-cases that localizers can browse. This
would be similar to what Pike did with Russian dates, or to what
I compiled in my blog post:

http://www.informationisart.com/20/

- tinker: try out different ideas and syntax of L20n code. This is
exactly what Pike did for Russian:

https://twitter.com/axelhecht/status/360548627422261248

> -Developer
> - Web developer
> - i18n/l10n engineer
> - The developer is interested in enabling multilingual content
> within their application/website. They understand the principles of i18n
> on the web and the challenges involved in providing a truly
> language-independent framework for localization. They also understand
> the complexities of language and the challenges associated with
> displaying/processesing various languages on a computer.

There are three parts of L20n that this kind of developers will be
interested in:

- the HTML API - what I, as a developer, need to do to my HTML in
order to make it localizable? Currently, we have a stub in github:

https://github.com/l20n/l20n.js/blob/master/docs/html.md

- the JavaScript API - the thing that localizes HTML is just a specila
instance of a more generic JS API. L20n.getContext() and friends,
and the methods of context instances are in this bucket. Again,
some form of the documentation lives on github now:

https://github.com/l20n/l20n.js/blob/master/docs/api.md

- L20n code itself - the developer needs to put a localizer's hat on
when they create L20n files for their original locale. In most of
the cases, this will be en-US, so I don't expect the developers to
make use of more advanced features of L20n. As in, they likely
won't need to learn it to an extent that allows ideas as complex as
the Russian dates example. A localizer-targeted cheatsheet would be
enough. I also don't think /learn is the right fit for this
audience. It's probably too long and too elementary. The default
text of the tinker is probably closer to what I had in mind:

http://l20n.github.io/tinker/

Putting these three parts together should be easy. Enter l20n/demo,
which you just clone and things Just Work™:

https://github.com/l20n/demo & http://l20n.github.io/demo/

> -Product manager
> - The PM is interested in evaluating L20n's ability to provide
> a comprehensive framework for accurate localization within a short
> timeframe. The PM understands some principles of i18n and l10n, but
> ultimately cares about it's interoperability within the organization's
> current tool chain and within existing l10n industry standards.

We currently don't have any documentation for the PMs, although I think
many of the bullet point advantages from our first Gaia pitch could be
built upon (you'll find it on the etherpad).

* * *

> Based on these descriptions, it seems that developers would need to
> learn how to enable L20n and what sort of L20n code they might
> encounter. They also need to understand how the .lol file type will
> interact within their own code.

Yes, see the 3rd bullet point in my reply under "Developer".

> PM's would be interested in the above information, as well as some
> performance related data and white pages on how L20n ultimately
> improved a localized product and the process by which it was
> localized.

Correct. I think we should leverage our Gaia pitch and create a list
of benefits your users and your developers reap from using L20n.

> Localizers would need to learn the principles, syntax, and use of
> L20n, ultimately aiming toward teaching them how to successfully code
> in L20n for their language.

And a 'yes' one more time :) As I explain above, I think learning can
be approach from a number of POVs:

- 'I have 30 minutes, I want to learn L20n' - that's the purpose of
/learn (maybe we should call it "Learn L20n in 30 minutes" similar
to http://learnxinyminutes.com/ ?)

- 'I have a problem, how do I solve it in L20n' -> collection of
use-cases,

- 'I've done this before, but I forgot the syntax' -> cheatsheet or
a specific chapter of /learn,

- (advanced localizers) 'I know my ways around code, just give me
something to play and experiment with' -> tinker

> I, personally, think that there should be a cheatsheet, but I don't
> think there needs to be one per audience.

The HTML and JS API cheatsheet is very different from L20n-syntax one.
I think we should have those two separately.

> Have I hit everything? Is there anything I've missed? Would you agree
> with the assessment of the target audiences for the L20n doc?

Yes, this was a great summary, thanks Jeff!

There's also a 4th audience that I would like to make sure we don't
forget: hackers interested in contributing to L20n. It's important
that we at least don't make their lives more difficult, and some
documentation can go a long way toward making them easier.

We currently have some docs for this audience in github and on MDN:

https://github.com/l20n/l20n.js/blob/master/docs/build.md
https://github.com/l20n/l20n.js/blob/master/docs/devel.md

https://developer.mozilla.org/en-US/docs/L20n/Contribute
https://developer.mozilla.org/pl/docs/L20n/Makefile

We've already seen some interest and participation outside of Mozilla
and I would like to improve the contributing docs before we release
one-dot-oh, which will be a great opportunity to attract new developers
to the project.

-stas


--
@stas