421084 - Investigate help changes needed for new helper app pane

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[Robert Kaiser]

The new helper app pane landed by bug 417590 is substantially different from the old one, so we need to make sure that help is correct for the new pane.

Comment 1

[Robert Kaiser]

Attachment: merge Firefox 3 support doc to our help

This patch basically takes the FF3 section for SUMO, and brings it into a nice form that fits our help. I'm open to suggestions, but I'd like both Ian and Stefan to look into this so the result will really fit our help.

Comment 2

[Ian Neal]

Comment on attachment 308251 [details] [diff] [review]
merge Firefox 3 support doc to our help

>+  <li><strong>Choose an application</strong>: To choose a local or web
>+    application to handle a type, select the application from the menu. If you
>+    want a local application that is not in the menu to handle the type, select
>+    <strong>Choose Application…</strong> from the menu and point
>+    &brandShortName; to its location.</li>
I do not see "Choose Application…" in the menu list, I see "Use other…" though.
>+  <li><strong>Choose a <!-- feature or --> plugin</strong>: If you want a
>+    <!-- feature or a --> plugin in &brandShortName; to handle the type, and one is
>+    available, select it from the menu.</li>
Is it worth including or describing the icon you would see to indicate the option is a plugin?
>+  <li><strong>Save on your computer</strong>: If you want to save the type on
>+    your computer, and it is possible to do so, select <strong>Save
>+    File</strong> from the menu. If you have selected the <strong>Automatically
>+    download files to specified download folder</strong> preference in the
>+    <strong>Downloads</strong> panel, &brandShortName; will save content of the
>+    type on your computer automatically. Otherwise, when you encounter the
>+    type, &brandShortName; will prompt you for a location on your computer to
>+    save it to.</li>
> </ul>

The general format for SM help usually seems to be of the form:
<li><strong>Button/Menu name</strong>: Select/Choose this to...
Other views?

Comment 3

[Stefan [:stefanh]]

Comment on attachment 308251 [details] [diff] [review]
merge Firefox 3 support doc to our help

-<p>The Helper Applications preferences panel allows you to control how
-  different file types are opened by other applications in
-  &brandShortName;:</p>
+<p>The Helper Applications preferences panel lets you choose applications and
+  other handlers to handle different types of content (e.g. PDF documents).
+  It shows you a list of content types and lets you select a handler for each
+  type.</p>
+<p>You can choose a local application to handle any type. For some types, you
+  can also choose a web application to handle the type, choose
+  <!-- a feature (like <a href="glossary.xhtml#live_bookmark">Live Bookmarks</a> for
+  feeds) or --> a <a href="glossary.xhtml#plugin">plugin</a> in &brandShortName; to
+  handle the type, or save the type on your computer.</p>
+<p>To choose a handler for a type, select the type from the list. The current
+  handler for the type will turn into a menu.

I think this is good. Also, nearly everything is said here, but I think it's worth mentioning the search field as well.

This is just an idea, but after "The current handler for the type will turn into a menu." you might be able to get away with some finishing lines mentioning the options and when they're available. Or something like "Depending on the type..."

Comment 4

[Ian Neal]

Comment on attachment 308251 [details] [diff] [review]
merge Firefox 3 support doc to our help

r- for the moment.

Comment 5

[Stefan [:stefanh]]

Comment on attachment 308251 [details] [diff] [review]
merge Firefox 3 support doc to our help

See comment #3 for suggestions. I think that'd work.

Comment 6

[Robert Kaiser]

Attachment: address review comments

Here's the patch with the previous comments addressed.

Comment 7

[Ian Neal]

Comment on attachment 319017 [details] [diff] [review]
address review comments

>Index: mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml
>===================================================================

>+<p>To choose a handler for a type, select the type from the list. The current
>+  handler for the type will turn into a menu. Open the menu and select the
>+  handler you want to handle the type. Depending on the actual type, a
>+  selection of the foillwoing options is availabe:</p>
"following" and "available"

>+  <li><strong>Choose an application</strong>: To choose a local or web
>+    application to handle a type, select the application from the menu. If you
>+    want a local application that is not in the menu to handle the type, select
>+    <strong>Use other…</strong> from the menu and point
>+    &brandShortName; to its location.</li>
Maybe "browse" instead of "point"

>+  <li><strong>Save on your computer</strong>: If you want to save the type on
>+    your computer, and it is possible to do so, select <strong>Save
perhaps "content of this type onto your computer" or "files" instead of "content"
>+    File</strong> from the menu. If you have selected the <strong>Automatically
>+    download files to specified download folder</strong> preference in the
>+    <strong>Downloads</strong> panel, &brandShortName; will save content of the
"this" instead of "the"?
>+    type on your computer automatically. Otherwise, when you encounter the
"this" instead of "the"?
>+    type, &brandShortName; will prompt you for a location on your computer to
"type of content"?
>+    save it to.</li>

>+<p><strong>Note:</strong> When a plugin is available to handle a type, and you
>+  choose another handler to handle that type, &brandShortName; will only use
>+  your chosen handler when you access the type directly. When the type is
>+  embedded inside a web page, &brandShortName; will continue to use the plugin
"original" or "default" in front of "plugin"?
>+  to handle the type. See also
"it" instead of "the type"?

r=me with those comments addressed/answered.

Comment 8

[Stefan [:stefanh]]

Comment on attachment 319017 [details] [diff] [review]
address review comments

Index: mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml
>===================================================================
>RCS file: /cvsroot/mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml,v
>retrieving revision 1.42
>diff -u -7 -p -r1.42 cs_nav_prefs_navigator.xhtml
>--- mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml	15 Dec 2007 04:26:16 -0000	1.42
>+++ mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml	2 May 2008 14:32:16 -0000
>@@ -217,80 +217,54 @@
> <ol>
>   <li>Open the <span class="mac">&brandShortName;</span>
>     <span class="noMac">Edit</span> menu and choose Preferences.</li>
>   <li>Under the Browser category, click Helper Applications. (If no
>     subcategories are visible, double-click Browser to expand the list.)</li>
> </ol>
> 
>-<p>The Helper Applications preferences panel allows you to control how
>-  different file types are opened by other applications in
>-  &brandShortName;:</p>
>+<p>The Helper Applications preferences panel lets you choose applications and
>+  other handlers to handle different types of content (e.g. PDF documents).
>+  It shows you a list of content types and lets you select a handler for each
>+  type. You can filter the list using the "Search" field. Entering any text
>+  there will narrow the list to entries containing that text either in the type
>+  description or the currently selected action.</p>
>+<p>You can choose a local application to handle any type. For some types, you
>+  can also choose a web application to handle the type, choose
>+  <!-- a feature (like <a href="glossary.xhtml#live_bookmark">Live Bookmarks</a> for
>+  feeds) or --> a <a href="glossary.xhtml#plugin">plugin</a> in &brandShortName; to
>+  handle the type, or save the type on your computer.</p>
>+<p>To choose a handler for a type, select the type from the list. The current
>+  handler for the type will turn into a menu. Open the menu and select the
>+  handler you want to handle the type. Depending on the actual type, a
>+  selection of the foillwoing options is availabe:</p>

Hmm, I read that as "Choose an application" etc are the choices that you *see* in the menu.
How about something like: "The current handler for the type will turn into a menu. Depending on the type (or "Depending on the actual type"), you can:"



>+  <li><strong>Choose an application</strong>: To choose a local or web
>+    application to handle a type, select the application from the menu. If you
>+    want a local application that is not in the menu to handle the type, select
>+    <strong>Use other…</strong> from the menu and point
>+    &brandShortName; to its location.</li>
>+  <li><strong>Choose a <!-- feature or --> plugin</strong>: If you want a
>+    <!-- feature or a --> plugin in &brandShortName; to handle the type, and one is
>+    available, select it from the menu.</li>
>+  <li><strong>Save on your computer</strong>: If you want to save the type on
>+    your computer, and it is possible to do so, select <strong>Save
>+    File</strong> from the menu. If you have selected the <strong>Automatically
>+    download files to specified download folder</strong> preference in the
>+    <strong>Downloads</strong> panel, &brandShortName; will save content of the
>+    type on your computer automatically. Otherwise, when you encounter the
>+    type, &brandShortName; will prompt you for a location on your computer to
>+    save it to.</li>

Now, my objection here is related to my previous comment (and not all choices are described?), but I'd prefer if this was laid out a bit differently. Combined with the previous suggestion you could write (in a unordered list, as before):

- Choose an application by selecting it from the menu. If you want a local..."
- Choose a plugin by selecting it from the menu
- Save the file on your computer by selecting Save File from the menu. If you have....
- Tell &brandShortName; to always ask ...

I also think that by doing it this way you don't need any bold text on the introduction words on each <li>. Just wrapping the actual terms that exists in the menu (Save File etc) in a <strong> should be enough.

> </ul>
> 
>-<p>To learn more about how to handle different file types with
>-  &brandShortName;, see
>+<p><strong>Note:</strong> When a plugin is available to handle a type, and you
>+  choose another handler to handle that type, &brandShortName; will only use
>+  your chosen handler when you access the type directly. When the type is
>+  embedded inside a web page, &brandShortName; will continue to use the plugin
>+  to handle the type. See also
>   <a href="nav_help.xhtml#plugins_and_downloads">Plugins and Downloads</a>.

The minus is mostly because you haven't updated this page (take a look at the Helper Applications section). Note: I'd remove as much as possible from there. For example, the whole section "For experienced users to fine-tune the Helper Applications preferences:" at line 1257 could be removed (unless IanN have some strong objection against this) - as you might noticed, it's just a burden to have duplicated content ;-)

Comment 9

[Robert Kaiser]

Attachment: address more review comments, also include nav_help

This patch should address all review comments, including the request to remove most of the related documentation from nav_help, pointing to the prefs help instead.

Comment 10

[Stefan [:stefanh]]

Comment on attachment 326190 [details] [diff] [review]
address more review comments, also include nav_help

>Index: mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml
>===================================================================
>RCS file: /cvsroot/mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml,v
>retrieving revision 1.43
>diff -u -7 -p -r1.43 cs_nav_prefs_navigator.xhtml
>--- mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml	6 May 2008 17:10:04 -0000	1.43
>+++ mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml	22 Jun 2008 18:59:39 -0000
>@@ -217,80 +217,53 @@
> <ol>
>   <li>Open the <span class="mac">&brandShortName;</span>
>     <span class="noMac">Edit</span> menu and choose Preferences.</li>
>   <li>Under the Browser category, click Helper Applications. (If no
>     subcategories are visible, double-click Browser to expand the list.)</li>
> </ol>
> 
>-<p>The Helper Applications preferences panel allows you to control how
>-  different file types are opened by other applications in
>-  &brandShortName;:</p>
>+<p>The Helper Applications preferences panel lets you choose applications and
>+  other handlers to handle different types of content (e.g. PDF documents).
>+  It shows you a list of content types and lets you select a handler for each
>+  type. You can filter the list using the "Search" field. Entering any text
>+  there will narrow the list to entries containing that text either in the type
>+  description or the currently selected action.</p>

1) I'd say "To filter the list, use the search field. Text entered in the search field will narrow the list..."

>+<p>You can choose a local application to handle any type. For some types, you
>+  can also choose a web application to handle the type, choose
>+  <!-- a feature (like <a href="glossary.xhtml#live_bookmark">Live Bookmarks</a> for
>+  feeds) or --> a <a href="glossary.xhtml#plugin">plugin</a> in &brandShortName; to
>+  handle the type, or save the type on your computer.</p>
>+<p>To choose a handler for a type, select the type from the list. The current
>+  handler for the type will turn into a menu. Open the menu and select the
>+  handler you want to handle the type. Depending on the actual type, you can:</p>
> 
> <ul>
>-  <li><strong>Specify how to handle files of each type</strong>:
>-    <ul>
>-      <li><strong>File types</strong>: Displays the file types that
>-        &brandShortName; uses. Select one of them to show the following
>-        information:
>-        <ul>
>-          <li><strong>Description</strong>: Displays a description of the
>-            selected file type.</li>
>-          <li><strong>Extension(s)</strong>: Displays the file extension(s) of
>-            the selected file type.</li>
>-          <li><strong>When encountered</strong>: Displays what kind of action
>-            that will be taken when &brandShortName; encounters the selected
>-            file type.</li>
>-        </ul>
>-      </li>
>-      <li><strong>New Type</strong>: Click this to add a new file type. You see
>-        a dialog box:
>-        <ul>
>-          <li><strong>Mime Type</strong>: Type the Mime type of the file type
>-            you want to add.</li>
>-          <li><strong>Description</strong>: Type a Descrition of the file
>-            type you want to add.</li>
>-          <li><strong>Extension</strong>: Type the file extension of the file
>-            type you want to add.</li>
>-          <li><strong>When a file of this type is encountered</strong>:
>-            Select one option from the checkboxes:
>-            <ul>
>-              <li><strong>Open it using the default application</strong>:
>-                Causes the the file to be opened by the default program in
>-                your systems settings.</li>
>-              <li><strong>Open it with</strong>: Causes the file to be
>-                opened by a program you specify. Use the Choose File button
>-                to locate the program on your disk</li>
>-              <li><strong>Save it to disk</strong>: The file will be saved
>-                to disk.</li>
>-            </ul>
>-          </li>
>-          <li><strong>Always ask me when handling files of this
>-            type</strong>: Select this to make the Download Dialog box always
>-            appear when files of this type are encountered.</li>
>-        </ul>
>-      </li>
>-      <li><strong>Edit</strong>: Click this to change the file-handling
>-        information of a selected file type.</li>
>-      <li><strong>Remove</strong>: Click this to remove a selected file
>-        type.</li>
>-    </ul>
>-  </li>
>-  <li><strong>Plugin Finder Service</strong>:
>-    <ul>
>-      <li><strong>Always use the Plugin Finder Service (PFS) to get 
>-        plugins</strong>: Select this to always use the Plugin Finder Service
>-        (PFS) whenever &brandShortName; needs a new plugin. If left
>-        unselected, the PFS is only used when a plugin location is not
>-        provided by the web page that requires the plugin.</li>
>-    </ul>
>-  </li>
>+  <li>Choose an application by selecting it from the menu. If you want a local
>+    application that is not in the menu to handle the type, select
>+    <strong>Use other…</strong> from the menu and browse &brandShortName; to its
>+    location.</li>

2) I know IanN proposed this, and I'm fine if he persists - after all, he's the expert here. It could be that I'm used to the native filepicker so I feel more that it's not seamonkey that does the browsing. Anyway, I'd rather say "and navigate to its location" instead of "and browse &brandShortName; to its location"

>+  <li>Choose a <!-- feature or --> plugin</strong> by selecting it from the menu.</li>

3) Please fix the xml parsing error here (remove the </strong>)

>+  <li>Save files of this type on your computer by selecting
>+    <strong>Save File</strong> from the menu. If you have selected the
>+    <strong>Automatically download files to specified download folder</strong>
>+    preference in the <strong>Downloads</strong> panel, &brandShortName; will
>+    save content of this type on your computer automatically. Otherwise, when
>+    you encounter this type, &brandShortName; will prompt you for a location on
>+    your computer to save it to.</li>
>+  <li>Tell &brandShortName; to <strong>always ask</strong> what to do when
>+    encountering this type. When you choose this option, a dialog will always be
>+    shown when files of this type are accessed, and you can choose how to handle
>+    that specific file from there.

4) And here (missing </li>)

> </ul>
> 
>-<p>To learn more about how to handle different file types with
>-  &brandShortName;, see
>+<p><strong>Note:</strong> When a plugin is available to handle a type, and you
>+  choose another handler to handle that type, &brandShortName; will only use

5) How about "choose another handler for that type" instead of "choose another handler to handle that type"?

>+  your chosen handler when you access the type directly. When the type is
>+  embedded inside a web page, &brandShortName; will continue to use the plugin
>+  to handle it. See also
>   <a href="nav_help.xhtml#plugins_and_downloads">Plugins and Downloads</a>.
> </p>
> 
> <p>[<a href="#navigator_preferences">Return to beginning of section</a>]</p>
> 
> <h2 id="location_bar">Browser Preferences - Location Bar</h2>
> 
>Index: mozilla/suite/locales/en-US/chrome/common/help/nav_help.xhtml
>===================================================================
>RCS file: /cvsroot/mozilla/suite/locales/en-US/chrome/common/help/nav_help.xhtml,v
>retrieving revision 1.74
>diff -u -7 -p -r1.74 nav_help.xhtml
>--- mozilla/suite/locales/en-US/chrome/common/help/nav_help.xhtml	7 May 2008 19:59:06 -0000	1.74
>+++ mozilla/suite/locales/en-US/chrome/common/help/nav_help.xhtml	22 Jun 2008 18:59:39 -0000
>@@ -1222,102 +1222,17 @@
> <h2 id="helper_applications">Helper Applications</h2>
> 
> <p>When files can not be used within &brandShortName;, you have to option to

6) Please fix the "you have to option" to be "you have the option"

r=me with 1-6 fixed. IanN should have the final call on my wording proposals, though - he's the expert here :-)

Comment 11

[Ian Neal]

(In reply to comment #10)
> (From update of attachment 326190 [details] [diff] [review])
> >Index: mozilla/suite/locales/en-US/chrome/common/help/cs_nav_prefs_navigator.xhtml
> >+<p>The Helper Applications preferences panel lets you choose applications and
> >+  other handlers to handle different types of content (e.g. PDF documents).
> >+  It shows you a list of content types and lets you select a handler for each
> >+  type. You can filter the list using the "Search" field. Entering any text
> >+  there will narrow the list to entries containing that text either in the type
> >+  description or the currently selected action.</p>
> 
> 1) I'd say "To filter the list, use the search field. Text entered in the
> search field will narrow the list..."
"To filter the list, use the search field. Text entered in there will narrow the list..."

Otherwise I agree with stefanh's comments.

Comment 12

[Ian Neal]

Comment on attachment 326190 [details] [diff] [review]
address more review comments, also include nav_help

so r=me with items 1-6 address plus my tweak.

Comment 13

[Robert Kaiser]

Checked in with those tweaks, thanks.