Plan for using support.mozilla.com as in-product help in Firefox 3

1 view
Skip to first unread message

David Tenser

unread,
Dec 5, 2007, 5:31:29 PM12/5/07
to
[Cross-posting to m.dev.l10n and m.support.planning]

We're getting closer and closer to a release of Firefox 3, which is
really exciting for everyone involved. For localizers and/or translators
this also means we'll soon need to update all the in-product help
content. There were early discussions in September about using
support.mozilla.com (SUMO) as the in-product help for Fx3, both
internally within the SUMO team, and with the development team
(specifically, with mconnor and beltzner).

The two major benefits of using SUMO as the in-product help, from a
product point of view, are:

* Ability to improve the content after a release
* Ability to show important notifications/messages if we e.g. have
regressions after a security update

After recent discussions with Pascal, Axel, Paul Kim, and mconnor, I am
proposing the following plan on how to make this a reality. I would very
much appreciate everyone's feedback on it. For a background of the SUMO
development, see http://blog.mozilla.com/sumo/roadmap/.

Here's the plan:

1. We complete SUMO milestones 0.2 and 0.3 (simplifying article
editing + release Firefox forums). ETA: mid-December.
* Meanwhile, some locales might already start hacking on
the in-product documentation, updating it for Fx3.
Other locales might wait.

2. Nelson (member of the TikiWiki community currently working with
us on SUMO) starts working on an "in-product html to wiki"
converter script. He estimates about 16 hours of work for that,
which translates to an ETA around beta 2 launch.
* Meanwhile, webdev and the SUMO team work on milestone 0.4
(Live Chat) to make sure we deliver our Q4 goals, which are
forums + chat.

3. We freeze the in-product help content on the trunk and perform the
import, verifying that all content is imported to SUMO and works.
ETA: after the holidays.

4. We get the localizers rolling on updating their respective pages
for Firefox 3 on SUMO instead of in-product, helping them out and
introducing them to the SUMO way of editing articles (which btw
will be a smoother experience compared to SUMO today).
* Meanwhile, Nelson and webdev works on 0.5 (localization
support; basically things like supporting a proper url
format and other things -- nothing that would block
localizers from hacking on their pages!) ETA: end of January
* Meanwhile, development can work on updating the in-product
help viewer based on a new specification. ETA: end of Feb?

There are obviously details omitted here, but that's the basic plan. For
localizers, the big change would be where and how to write and maintain
the Firefox documentation, but we (the SUMO team) would do the hard work
of importing your content to the new platform. We might need to do some
things manually, but in general, the import script should do the heavy
lifting for us.

How does this sound to you guys? We would really rely on everyone here
for this to become a reality. :)

- David (SUMO project manager)

Cédric Corazza

unread,
Dec 5, 2007, 5:47:39 PM12/5/07
to
Hi,
If I understood well, the decision to move the Firefox Help to the Web
has been made, right?
The French locale will have a big problem with this : we used the *.dtd
entities in the Help content to be in synch with Firefox menus, dialogs,
buttons and so on.
Will the converter script handle this? If not, it will take us quite
some time to manually substitute them.
Another concern is : will the "Off line" feature be ready for Firefox 3,
to "cache" the Help locally from the web site. If not, this would mean
that one has to be mandatorily online to consult help.

Cédric

David Tenser

unread,
Dec 6, 2007, 7:02:58 AM12/6/07
to
Cédric Corazza wrote:
> Hi,
> If I understood well, the decision to move the Firefox Help to the Web
> has been made, right?

Hi Cédric,

Thanks for the response. I'm mainly looking for feedback from you guys
at this point, and a decision hasn't been made. However, I really
believe this would benefit Firefox and it looks like it could work. :)

We need to make the final decision before SUMO 0.3 is finished, which
should give us a couple of weeks to clear out any issues or concerns.

> The French locale will have a big problem with this : we used the *.dtd
> entities in the Help content to be in synch with Firefox menus, dialogs,
> buttons and so on.
> Will the converter script handle this? If not, it will take us quite
> some time to manually substitute them.

The import script would convert the dtd entities into the actual word,
e.g. "Firefox" instead of &shortBrandName;.

The question is how to handle the localized entities. We would have to
run the script through you guys first so you have a chance to localize
the script first (should only require one translation per dtd entity).
Otherwise you would end up with the English menus, dialogs, etc.

It would obviously be cool if the site itself could support dtd
entities, but I doubt that's possible. We could theoretically develop
something similar for the wiki (e.g. that you would type %%fileNewTab%%
and it would expand to "New Tab" if en-US is chosen as the locale), but
I think that's something we shouldn't focus on at this point. However,
that's definitely possible.

So, to answer your question: yes, the converter script would handle it,
but we would need your help to prepare the script for your locale.

> Another concern is : will the "Off line" feature be ready for Firefox 3,
> to "cache" the Help locally from the web site. If not, this would mean
> that one has to be mandatorily online to consult help.

That's a good point that we've discussed before. Yes, we should be able
to utilize the offline cache feature, but it depends more on the
development team's availability. We will work with them to create a
specification for this.

- David

David Tenser

unread,
Dec 6, 2007, 10:58:44 AM12/6/07
to
Ognyan Kulev wrote:
> David Tenser wrote:
>> I agree that would be cool. :) What we found was that there were no good
>> technical solutions that used Jabber or IRC integration. What we settled
>> on is OpenFire (http://www.jivesoftware.com/products/openfire/).
>
> Great!
>
>> This means a simple web interface (no software needed) for the users
>> requesting help; it will be neatly integrated to the SUMO website.
>> Helpers, on the other hand, need to download a small chat client
>> (http://www.jivesoftware.com/products/spark/).
>
>> As we get time to evaluate this product, we might find out about better
>> solutions that we could integrate with more open chat clients, e.g.
>> Pidgin/Gaim, or IRC.
>
> Since OpenFire is XMPP server that (in SUMO's case) is used for
> chatrooms, I see no problem in using any XMPP client by helpers and
> their own JID @ other server, right? I consider this the best possible
> solution.

I think I read somewhere that it should be possible to use an
independent client, at least in the future. Lucy, do you know any more
about this?

Majken Connor

unread,
Dec 6, 2007, 8:24:55 PM12/6/07
to support-...@lists.mozilla.org

> _______________________________________________
>

You can already use things like Adium to access the group chat portions of
the openfire software, but not the Fastpath portion, which is what is used
to accept help requests from web users. I can't remember if you can invite
someone who is using the basic chat via adium into a group chat with a web
user (when you invite someone in to help you with a user, I believe it
passes it off to the basic group chat). I'll make a note to try that out
again.

Fastpath currently is not open source, so we'd have to put in a request with
Jive to somehow make it work in other clients. I would imagine this is
possible, it would just need to pass for instance the chat request as a
plain message and require the helper to reply with "yes" or "accept" to take
the request, and script some other commands.

There is work on creating a web version of the spark client, but so far no
plans to incorporate fastpath into it (would probably be better to try and
make fastpath work with adium etc).

Nukeador

unread,
Dec 7, 2007, 8:49:10 AM12/7/07
to
What about the locales that have their own community documentation?

I mean, having FF3 help online could be better or worse but, that would
mean that we also have to translate the whole SUMO (not just in-product
pages)?

For example, in the Spanish community we have our how documentation for
Firefox, Thunderbird, SeaMonkey... etc and for that reason most of our
localizers think that translating SUMO is a waste of time.

I think that there won't be any problem to translate only in-product
pages for Ff3 at SUMO and point to the community documentation for
Firerfox help, right?

signature.asc

David Tenser

unread,
Dec 7, 2007, 10:50:36 AM12/7/07
to Nukeador
Nukeador wrote:
> What about the locales that have their own community documentation?
>
> I mean, having FF3 help online could be better or worse but, that would
> mean that we also have to translate the whole SUMO (not just in-product
> pages)?
>
> For example, in the Spanish community we have our how documentation for
> Firefox, Thunderbird, SeaMonkey... etc and for that reason most of our
> localizers think that translating SUMO is a waste of time.

I view SUMO's focus as one of its strengths. It's hard to write
documentation that covers many applications at the same time. We have
the benefit of _only_ supporting Firefox, which gives us to ability to
provide specific Firefox screenshots (and in the future, screencasts),
and it makes the documentation less cluttered.

As you point out, though, the limited scope of SUMO is a problem for
some communities that are more oriented to Mozilla projects as a whole.
One of the main reasons why SUMO exists is to make it easier for Firefox
users to find good support. Part of that will, initially, be leveraged
by linking to these community-supported sites.

>
> I think that there won't be any problem to translate only in-product
> pages for Ff3 at SUMO and point to the community documentation for
> Firerfox help, right?
>

Yes, we are right now just talking about the current in-product help
content. We want to move that out of the browser and up on the server,
so we don't end up with duplicate content (and the other benefits I
listed previously). The only difference here is that the in-product help
will be grabbed off the internet instead of stored locally as static web
pages.

I don't see any problems with communities having their own Firefox
documentation -- on the contrary, I think we should promote that content
on SUMO. For example, the start page for the Spanish version of SUMO
should have prominent links to the excellent third-party content that
already exists. Exactly how we will do that is something I'd be
interested in hearing your opinion about.

Of course, depending on the license of that documentation, volunteers
might port some of it over to SUMO to make the Spanish SUMO experience
more complete. All articles on SUMO are licensed under a Creative
Commons Attribution-Share Alike 3.0 License.

By the way, SUMO will have locale fallback support, which means that if
you select Spanish and do a search, it will also list any pages not yet
translated to Spanish. The fallback order will be specified by the
language settings in Firefox, so if you have e.g. Portuguese as your
second language, that language would be used for any articles not yet
translated to Spanish (but translated to Portugese -- otherwise it would
show the English page).

- David

Robert Kaiser

unread,
Dec 7, 2007, 6:38:39 PM12/7/07
to
David Tenser wrote:
> I view SUMO's focus as one of its strengths.

Sorry to be blunt, but if it's meant to be and stay focused of FF only,
it's misnamed. It shouldn't be SUMO then, but SUFOX or something like
that (rather nit SUFF as that may not sound good for German users).

Robert Kaiser

Majken Connor

unread,
Dec 8, 2007, 1:08:35 AM12/8/07
to support-...@lists.mozilla.org
SUMO is the internal codename for the project, more appropriate would be
SUMOCO but that isn't already a word. The url is support.mozilla.com and
the site will say "Firefox Support" on it, not SUMO.

> _______________________________________________
> support-planning mailing list
> support-...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/support-planning
>

Ricardo Palomares Martinez

unread,
Dec 9, 2007, 8:41:22 AM12/9/07
to
David Tenser escribió:

> [Cross-posting to m.dev.l10n and m.support.planning]
>
> (...) There were early discussions in September about using
> support.mozilla.com (SUMO) as the in-product help for Fx3, (...)

>
> After recent discussions with Pascal, Axel, Paul Kim, and mconnor, I am
> proposing the following plan on how to make this a reality. (...)

>
> 4. We get the localizers rolling on updating their respective pages
> for Firefox 3 on SUMO instead of in-product, helping them out and
> introducing them to the SUMO way of editing articles (which btw
> will be a smoother experience compared to SUMO today).


Is there any policy about who can localize articles in SUMO (and edit
localized ones)? I ask this because I'm afraid that a wiki-like system
where people can just create an account for themselves and start to
write will lead to more people helping out (which is good) but
providing a lesser degree of quality in the localization or even
grammar and ortographic errors (which, of course, is bad). Since I
guess SUMO contents will be accessed through the help viewer, it could
make to appear that product localization quality has gone down.

TIA

--
If it's true that we are here to help others,
then what exactly are the OTHERS here for?

Chris Ilias

unread,
Dec 9, 2007, 10:36:28 PM12/9/07
to
On 12/9/07 8:41 AM, _Ricardo Palomares Martinez_ spoke thusly:

> Is there any policy about who can localize articles in SUMO (and edit
> localized ones)? I ask this because I'm afraid that a wiki-like system
> where people can just create an account for themselves and start to
> write will lead to more people helping out (which is good) but
> providing a lesser degree of quality in the localization or even
> grammar and ortographic errors (which, of course, is bad). Since I
> guess SUMO contents will be accessed through the help viewer, it could
> make to appear that product localization quality has gone down.

All article changes are made to a staging copy. Only people with
reviewer permissions can approve the edits (thus applying the change to
the live version of the article). This is partially implemented on
support.mozilla.com, and the next round of patches to implement this are
being tested on support-stage.mozilla.org.

I assume translators of in-product help will need to be given reviewer
permissions as soon as they want.

For more info <http://wiki.mozilla.org/Support:PRD>

David Tenser

unread,
Dec 10, 2007, 9:28:42 AM12/10/07
to

SUMO as a code-name is irrelevant, but the site is actually called
"Firefox Support" (but the heading is still "Support," which will change
any day now; already changed on the staging server).

The url is a bit misleading, but most of mozilla.com focuses on Firefox
anyway. This is more of a marketing issue (same with addons.mozilla.com,
which takes you to a page called "Firefox Addons."

David Tenser

unread,
Dec 10, 2007, 9:32:33 AM12/10/07
to

A policy we've established (but not yet tried, since we don't have l10n
yet) is to have someone, or someones, responsible for a locale. This
would mean that there would be a limited number of people with review
permission. Anyone would still be free to suggest edits, but all edits
are queued for review by the reviewers.

So, for example, if there are two Spanish localizers responsible for the
in-product content today, those two would be given review permissions
right away. Then other contributors could do edits on the pages, and
some of these contributors might prove themselves to be skilled writers
and be given review permissions too, if the locale owner wants it.

Does that make sense?

Stanisław Małolepszy

unread,
Dec 10, 2007, 1:32:05 PM12/10/07
to
On 6 Gru, 13:02, David Tenser <djst.mozi...@gmail.com> wrote:

> The import script would convert the dtd entities into the actual word,
> e.g. "Firefox" instead of &shortBrandName;.

Hi David,

Thank you for starting this discussion. From what I see in the local
communities it is very needed.

Regarding the above quote: one of the benefits of having an in-product
support and using entities is that it is very easy for anyone to
change the right entity and publish a browser of their own, based on
Firefox.

If we move all the help pages to SUMO, which as you stated basically
is a *Firefox* support site, this flexibility will be lost. It will be
'Firefox' everywhere. Do you plan on enabling other projects to use
the online help sites?

Futhermore, with this change (having 'firefox' name hardcoded) we gain
some linguistic flexibility. Let me illustrate: in Polish, we decline
nouns as well as we use different grammatical forms for masculine and
feminine nouns. Since using an entity doesn't allow any of these, we
used an auxiliary noun 'przeglądarka' (browser) before 'Firefox',
which we could decline and which we know is feminine. So we would
write "Informacje o przeglądarce Mozilla Firefox" to say "Information
about Mozilla Firefox" -- we decline przeglądarka -> przeglądarce, and
Mozilla Firefox (inserted with an entity) remains unchanged. Now, this
makes for a bit more formal register of a text, but sometimes, it just
sounds weird. If we knew that SUMO's going to hardcode the Firefox
name throughout the help files, we could translate normally, without
tricks of this sort.

Anyways, the point is: taking out the entities will require you to
have localizers review the texts. All of them. Even if they don't
change anything (I don't if we would in Polish, the above was just a
illustration), they will need a couple of days to go through all this
content, because probably the import script won't handle the plethora
of strange cases in different languages, like the one I described
above.

--Staś

Ricardo Palomares Martinez

unread,
Dec 10, 2007, 3:57:26 PM12/10/07
to
David Tenser escribió:

> Ricardo Palomares Martinez wrote:
>>
>> Is there any policy about who can localize articles in SUMO (and edit
>> localized ones)?
>
> A policy we've established (but not yet tried, since we don't have l10n
> yet) is to have someone, or someones, responsible for a locale. This
> would mean that there would be a limited number of people with review
> permission. Anyone would still be free to suggest edits, but all edits
> are queued for review by the reviewers.
> (...)
> Does that make sense?


It sounds good. :-) In case an edit is to be rejected, I assume it
would be as easy as in a MediaWiki (like MDC), clicking an "Undo" link
for every "bad" revision. Am I right?

David Tenser

unread,
Dec 10, 2007, 4:31:03 PM12/10/07
to
Ricardo Palomares Martinez wrote:
> David Tenser escribió:
>> Ricardo Palomares Martinez wrote:
>>> Is there any policy about who can localize articles in SUMO (and edit
>>> localized ones)?
>> A policy we've established (but not yet tried, since we don't have l10n
>> yet) is to have someone, or someones, responsible for a locale. This
>> would mean that there would be a limited number of people with review
>> permission. Anyone would still be free to suggest edits, but all edits
>> are queued for review by the reviewers.
>> (...)
>> Does that make sense?
>
>
> It sounds good. :-) In case an edit is to be rejected, I assume it
> would be as easy as in a MediaWiki (like MDC), clicking an "Undo" link
> for every "bad" revision. Am I right?
>
> TIA
>

Yes, it's basically the same as in MediaWiki in terms of revision
history. I'd encourage you to create an account and find out more and
get a feeling of how it works (but wait a few days -- we're in the
middle of completing the 0.2 milestone which gives us better contributor
tools!). We're also available in the #sumo channel on irc.mozilla.org in
case you have questions or comments (and of course,
mozilla.support.planning is a good place to discuss things).

We pretty much rely on feedback from people to know how to do this
right. The goal is to really create a good platform for support.

David

David Tenser

unread,
Dec 12, 2007, 5:47:25 PM12/12/07
to
Stanisław Małolepszy wrote:
> On 6 Gru, 13:02, David Tenser <djst.mozi...@gmail.com> wrote:
>
>> The import script would convert the dtd entities into the actual word,
>> e.g. "Firefox" instead of &shortBrandName;.
>
> Hi David,
>
> Thank you for starting this discussion. From what I see in the local
> communities it is very needed.

I'm glad to hear that.

>
> Regarding the above quote: one of the benefits of having an in-product
> support and using entities is that it is very easy for anyone to
> change the right entity and publish a browser of their own, based on
> Firefox.

You are absolutely right in that by keeping in-product documentation
local/offline and with entities for things like the product name, we
make it much easier for people who want to create a separate product
based on Firefox.

However, the focus of SUMO is on users and the community.

* We want to provide our 100+ million users with a healthy support
channel where they know they will find the answer to their question.
We're getting there. :)

* We want to provide the community with a platform that makes it easy to
contribute and improve the support. By using the plain word Firefox
instead of &shortBrandName, we remove one technical barrier for people
who are skilled writers, but not programmers. The result is, hopefully,
more content writers.

By moving the in-product content to the web, we unfortunately lose some
of the flexibilities, but the gains are much more significant. Some
examples:

* Instead of (or, rather, in addition to) an article about tabbed
browsing, we can actually show a video/screencast of how to use tabs.

* Instead of detecting, and living with, a typo in the documentation, we
can fix it even if Firefox 3.x is already released.

* With powerful site statistics and metrics, we can see exactly what
kind of information people are looking for, and constantly improve our
content based on real data.

>
> If we move all the help pages to SUMO, which as you stated basically
> is a *Firefox* support site, this flexibility will be lost. It will be
> 'Firefox' everywhere. Do you plan on enabling other projects to use
> the online help sites?

My vision is that we will create a successful support platform for
Firefox. It will be very tailored towards support, and will for example
have specific forum features that are only useful to support sites.
We're doing this with the help of the TikiWiki community and the web
development team at Mozilla.

Now, once we have a high quality platform for support, I would love to
share that with other open source projects, and perhaps more important
for us, other Mozilla projects. Right now, the focus is on Firefox
because of the incredible amount of users we have, in contrast to how
pathetic our current mozilla.org/support/firefox/ content is today. (And
I'm being self-critical, as I wrote a fair share of that content!)

>
> Futhermore, with this change (having 'firefox' name hardcoded) we gain
> some linguistic flexibility. Let me illustrate: in Polish, we decline
> nouns as well as we use different grammatical forms for masculine and
> feminine nouns. Since using an entity doesn't allow any of these, we
> used an auxiliary noun 'przeglądarka' (browser) before 'Firefox',
> which we could decline and which we know is feminine. So we would
> write "Informacje o przeglądarce Mozilla Firefox" to say "Information
> about Mozilla Firefox" -- we decline przeglądarka -> przeglądarce, and
> Mozilla Firefox (inserted with an entity) remains unchanged. Now, this
> makes for a bit more formal register of a text, but sometimes, it just
> sounds weird. If we knew that SUMO's going to hardcode the Firefox
> name throughout the help files, we could translate normally, without
> tricks of this sort.

So this sounds like something that you could work on afterwards, when
the content is up on the site. I expect there to be a lot of handholding
to get everyone on SUMO, because right now some things are still a mess.
We're getting better and better, though, and I'm going to blog about the
improvements we made this week soon.

>
> Anyways, the point is: taking out the entities will require you to
> have localizers review the texts. All of them. Even if they don't
> change anything (I don't if we would in Polish, the above was just a
> illustration), they will need a couple of days to go through all this
> content, because probably the import script won't handle the plethora
> of strange cases in different languages, like the one I described
> above.

Yes, definitely. I would hope that the people who are responsible for
the in-product content today would be responsible (reviewers/admins) for
that locale. These people would have to read through the documentation.
Obviously, that could be a tough job for some people with limited time,
and I'm hopeful that we can find other people to help out when needed. I
personally understand Swedish, English, Norwegian, and Danish, so maybe
I could help out with those locales. My Polish is a little rusty, though. :)

- David

Reply all
Reply to author
Forward
0 new messages