In-product help content for Firefox 3
David Tenser
original idea has been to take the current Firefox 2 content, import it
to SUMO, then update it for Firefox 3. But what about the new features?
What do we want to add? Do we want to remove anything from the existing
documentation?
A quick look at the current Firefox 2 in-product documentation gives me:
* Using Firefox (using_firebird.xhtml)
o This is definitely the most questionable of the documents,
as it's basically a catch-all article about everything from
navigating web pages, searching, copying text with Ctrl+C,
saving web pages, printing, etc. I'm not sure what to do
with it. We should figure out what Firefox features we want
to cover and make a list of those instead of this general
"Using Firefox" document.
* Using the Download Manager (download_manager.xhtml)
o This needs to be updated to include the new offline resume
and new UI.
* Customization (customization.xhtml)
o The document is very general and probably doesn't have to
update much, except a few links to more detailed tutorials
already on SUMO. Would be an incentive for people to
translate those linked tutorials too, but should not be a
requirement.
* Preferences/Options (prefs.xhtml)
o Obviously needs to be updated here and there. We already
have a better version on SUMO with screenshots, but it needs
to be updated for Firefox 3 too. We probably want to import
the localized versions anyway. Or do we?
* Controlling Pop-ups (popup.xhtml)
o Essentially unchanged.
* Managing Cookies (cookies.xhtml)
o Some of the UI has changed, but other than that, the content
is mostly correct.
* Tabbed Browsing (tabbed_browsing.xhtml)
o Almost no changes required.
* Keyboard Shortcuts (shortcuts.xhtml)
o Some updates needed, but general structure is the same.
* Mouse Shortcuts (mouse_shortcuts.xhtml)
o Same as Keyboard Shortcuts.
* Accessibility Features (accessibility.xhtml)
o Minor updates required.
* Menu Reference (menu_reference.xhtml)
o Updates required, but general structure is the same.
* Help for Internet Explorer Users
o Unchanged.
To me, it still feels like it would make sense to do an in-product ->
SUMO article import for each locale, save for the "Using Firefox"
article. We should then create a list of features that we want to cover
-- with an emphasis on /basic/ features, e.g.:
* Places
* Location Bar
* ...
Basically, the new "in-product" help will be a subset of the articles
available in SUMO. We need to decide on a sensible subset, and,
preferably, use as much of the current in-product content as possible to
minimize work for localizers. We could, for example, decide that we want
a separate article about Add-ons
(http://support.mozilla.com/kb/Customizing+your+Firefox+with+add-ons),
but that means all localizers need to translate it from scratch. Or, we
could just settle on what's already covered in customization.xhtml above.
David
Chris Ilias
> To me, it still feels like it would make sense to do an in-product ->
> SUMO article import for each locale, save for the "Using Firefox"
> article. We should then create a list of features that we want to cover
> -- with an emphasis on /basic/ features, e.g.:
>
> * Places
> * Location Bar
> * ...
>
> Basically, the new "in-product" help will be a subset of the articles
> available in SUMO. We need to decide on a sensible subset, and,
> preferably, use as much of the current in-product content as possible to
> minimize work for localizers. We could, for example, decide that we want
> a separate article about Add-ons
> (http://support.mozilla.com/kb/Customizing+your+Firefox+with+add-ons),
> but that means all localizers need to translate it from scratch. Or, we
> could just settle on what's already covered in customization.xhtml above.
I often prefer the wording of the in-product stuff; so I think it would
be better to import all the in-product help, then if there are aspects
of the current KB articles that we feel are better, we can then import
those aspects into the stuff imported from in-product and do away with
the KB versions that were created from scratch. (Did that make sense?)
After that, we can choose which articles to use for Fx3
virtual-in-product help.
Axel Hecht
One of the tasks that remain is to fix up the links to in-product help
within firefox. So we need to fix those links reasonably soon, in
particular when we want to split existing pages.
Axel
David Tenser
From what I can see, the only in-product links we have that link to
specific help files are the Help/? button in the Options/Preferences
window. Are there other links?
Steffen Wilberg
>> within firefox. So we need to fix those links reasonably soon, in
>> particular when we want to split existing pages.
>
> From what I can see, the only in-product links we have that link to
> specific help files are the Help/? button in the Options/Preferences
> window.
> Are there other links?
The Page Info window has the F1 button hooked up to the pageinfo_general
topic, but we don't have a document on Page Info, so it opens the
welcome page.
You can search for helpTopic in the tree like this:
http://mxr.mozilla.org/seamonkey/search?string=helpTopic&find=browser&findi=&filter=&tree=seamonkey
Steffen
David Tenser
>>> One of the tasks that remain is to fix up the links to in-product
>>> help within firefox. So we need to fix those links reasonably soon,
>>> in particular when we want to split existing pages.
>>
>> From what I can see, the only in-product links we have that link to
>> specific help files are the Help/? button in the Options/Preferences
>> window.
> Correct.
>
> > Are there other links?
> The Page Info window has the F1 button hooked up to the pageinfo_general
> topic, but we don't have a document on Page Info, so it opens the
> welcome page.
Does that mean it's Windows/Linux only, as the Mac has F1 connected to
OS features instead? I can definitely see the benefit of having this
dialog explained in a kb article and connected to a Help/? button -- in
fact, I think all dialogs should have documentation, e.g.
Bookmarks/Library, Customize Toolbar, Import, etc. The question is how
likely it is that we are going to have theses articles translated to
other languages. The more articles, the more work for everyone.
What do people think? Is it better to define a larger set of
tutorials/how-to's as "in-product" help and risk that few locales decide
to translate them; or is it better to keep the set of "in-product"
articles to a minimum and thus increase the likeliness of them getting
localized?
>
> You can search for helpTopic in the tree like this:
> http://mxr.mozilla.org/seamonkey/search?string=helpTopic&find=browser&findi=&filter=&tree=seamonkey
Thanks, that's very helpful!
Axel Hecht
In the index and search rdfs, there are a bunch of links as well, not
sure what will happen to that, but I'd expect that to be kept locally?
Just guessing.
Axel
David Tenser
Where are these rdfs? If you mean e.g.
http://lxr.mozilla.org/mozilla/source/browser/locales/en-US/chrome/help/search-db.rdf,
that file would not be needed since we're using Google search on SUMO
instead.
Do you mean keeping some help content locally? That is not the idea,
since that would mean we would have to still keep the in-product help
viewer window. The idea is to simply launch a separate Firefox window
(possibly sans some chrome like the status and location bar), pointing
to a local .xul page that will in turn show some sort of "loading" UI
feedback while launching the SUMO website (with the appropriate kb
article) in the background. We wouldn't use a local search box in the
chrome; the search would be performed on the site.
Maybe I just misunderstood what you meant, but wanted to clarify this
anyway. :)
Steffen Wilberg
>> The Page Info window has the F1 button hooked up to the
>> pageinfo_general topic, but we don't have a document on Page Info, so
>> it opens the welcome page.
>
> Does that mean it's Windows/Linux only, as the Mac has F1 connected to
> OS features instead?
http://bonsai.mozilla.org/cvsblame.cgi?file=/mozilla/browser/base/content/pageinfo/pageInfo.xul&rev=1.13&mark=104#98
This is a bug, since it should be Cmd+? on Mac like in the main window
(or disabled since there's no help content for that yet).
The options window should respond to F1/Cmd+? as well, but doesn't yet.
Steffen
Steffen Wilberg
>>> specific help files are the Help/? button in the Options/Preferences
>>> window. Are there other links?
>>
>> In the index and search rdfs, there are a bunch of links as well, not
>> sure what will happen to that, but I'd expect that to be kept locally?
>> Just guessing.
>>
>> Axel
>
> Where are these rdfs? If you mean e.g.
> http://lxr.mozilla.org/mozilla/source/browser/locales/en-US/chrome/help/search-db.rdf,
> that file would not be needed since we're using Google search on SUMO
> instead.
These two files are used to generate the table of contents displayed on
the sidebar:
http://mxr.mozilla.org/seamonkey/source/toolkit/locales/en-US/chrome/mozapps/help/help-toc.rdf
http://mxr.mozilla.org/seamonkey/source/browser/locales/en-US/chrome/help/firebird-toc.rdf
You'd have to modify/replace them if you want to keep the help viewer,
but you don't need them if you just use some sort of web page.
Steffen
Steffen Wilberg
> These two files are used to generate the table of contents displayed on
> the sidebar:
> http://mxr.mozilla.org/seamonkey/source/toolkit/locales/en-US/chrome/mozapps/help/help-toc.rdf
>
> http://mxr.mozilla.org/seamonkey/source/browser/locales/en-US/chrome/help/firebird-toc.rdf
>
>
> You'd have to modify/replace them if you want to keep the help viewer,
> but you don't need them if you just use some sort of web page.
I forgot about the Help buttons in the options window. If you click the
help button, the help viewer is opened with a topic defined by
helpTopic. That topic is from firebird-toc.rdf, which links to the
appropriate section in prefs.xhtml.
The code for that context-sensitive help is in
http://mxr.mozilla.org/seamonkey/source/toolkit/content/widgets/preferences.xml,
search for "help".
Steffen
David Tenser
Yeah, we would probably change the context-sensitive help to point to
specific articles on SUMO instead. mconnor mentioned using something
similar to what we have today, so we don't end up hard-coding URLs to
SUMO in Firefox 3. Instead, we would use some sort of lookup table.
The thing I'd like to discuss asap is what content we want to link to
from the product, so we have a list of articles that would need to be
translated. And as I mentioned previously, we have a script that can
import the current in-product help for all locales and put it up on
SUMO, so that content would obviously save translators a lot of time.
Steffen Wilberg
> specific articles on SUMO instead.
> mconnor mentioned using something
> similar to what we have today, so we don't end up hard-coding URLs to
> SUMO in Firefox 3. Instead, we would use some sort of lookup table.
You could send help topics like "prefs-main" to sumo and let sumo sort
out which article to show.
> The thing I'd like to discuss asap is what content we want to link to
> from the product, so we have a list of articles that would need to be
> translated. And as I mentioned previously, we have a script that can
> import the current in-product help for all locales and put it up on
> SUMO, so that content would obviously save translators a lot of time.
Why not start with everything we have right now in built-in help?
I count more localizations of prefs.xhtml (58) than shipped locales for
Firefox on the 1.8 branch (45):
http://mxr.mozilla.org/l10n/find?string=prefs.xhtml
http://mxr.mozilla.org/mozilla1.8/source/browser/locales/shipped-locales
I pretty much agree with your first post to this topic, give
using_firebird.xhtml a good beating, but more or less keep the rest.
Steffen
Axel Hecht
Note, all locales ship prefs.xhtml, but not all of them ship a
translated one. So the mxr count doesn't count.
Axel
David Tenser
We noticed that too when trying to do an inventory of what locales have
translated content. The number of actually translated locales seem to be
a lot less (will come back with a specific number soon).
David Tenser
> Axel Hecht wrote:
>>
>> translated one. So the mxr count doesn't count.
>>
>> Axel
>
> We noticed that too when trying to do an inventory of what locales have
> translated content. The number of actually translated locales seem to be
> a lot less (will come back with a specific number soon).
Locales with translated in-product help content
* ca
* cs
* de
* el
* es-AR (partial)
* es-ES
* eu
* fa
* fi
* fr
* fy-NL
* gu-IN (partial)
* he
* hu
* it
* ja
* ko
* lt
* mn
* nb-NO
* nl
* nn-NO
* pa-IN
* pl
* pt-PT
* ro
* ru
* rw
* sk
* sl (partial)
* sq
* sv-SE
* tr
* uk
* zh-CN
* zh-TW
These two locales report their files as binary for some reason. Anyone
who knows why?
* lv
* ta
Axel Hecht
that the right document to start from?
Should we file bugs on the tasks laid out in that document?
Axel
Jason Barnabe (np)
What will we do with articles that link to articles that won't be in
in-product help? Link to the sumo article? Drop the links (and any
accompanying text)?
Chris Ilias
> I just ran across http://wiki.mozilla.org/Support/Firefox3:Articles, is
> that the right document to start from?
>
> Should we file bugs on the tasks laid out in that document?
I'd say no. I created that page, as an inventory of KB articles that
needed to be created/updated for Firefox 3. It was based on my own run
through KB articles, and Sheppy's list at
<http://developer.mozilla.org/en/docs/Firefox_3_for_developers#New_features_for_end_users>.
(It's a live document, by the way; so if anyone sees other KB articles
that will need updating for Firefox 3, please add. :-) )
What David is referring to is the articles used for Firefox 3
virtual-in-product help content.
David Tenser
> What will we do with articles that link to articles that won't be in
> in-product help? Link to the sumo article? Drop the links (and any
> accompanying text)?
I'm not 100% sure what you mean, but I'm going to assume you refer to
links from in-product articles to non-in-product articles. In those
cases, I think that should just work like any other of our wiki links:
if the page is not translated to the current locale the user is viewing
the site in, the fallback locale (e.g. English) will be used, with a
notification at the top of the article saying: "This articles has not
yet been translated. Feel free to help us out etc"
Relevant bugs:
https://bugzilla.mozilla.org/show_bug.cgi?id=398353
https://bugzilla.mozilla.org/show_bug.cgi?id=398352
https://bugzilla.mozilla.org/show_bug.cgi?id=398354
Chris Ilias
I may be mistaken, but I think he was referring to the need o be online,
to access the linked content.
Jason Barnabe (np)
I was referring to whether we would indeed be linking from in product
help to out of product help, not necessarily anything about
localization or being online.
I can see some situations with online content that would make us look
a bit stupid, though, for example linking to an article that describes
why Firefox can't access the Internet.
David Tenser
The in-product landing page on SUMO (e.g.
support.mozilla.com/en-US/kb/Firefox+Help) will use a search that will
only list the non-troubleshooting articles, as discussed in Toronto.
There will be a clear path from those search results to access the full
site/search.
There are a number of unfiled bugs that we need to make sure this will
work smoothly. For example, the Related Articles sidebar will need a
similar kind of filter based on category, and it would certainly be nice
if the poll could be different ("Did this article solve a problem you
had in Firefox?" doesn't make sense for in-product help).