652328 - Update help for redesigned Add-ons Manager

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[rsx11m]

Toolkit has made substantial changes to the Add-ons Manager, now opening in a content tab rather than a dialog window. Also, "Add-on Manager" was pluralized to "Add-ons Manager", which needs to be changed in any links or Help contents where the Add-ons Manager is mentioned. Beyond that, description of appearance and action (primarily in customize_help.xhtml) will need to be updated.

Comment 1

[Jens Hatlak (:InvisibleSmiley)]

Cf. bug 641252 comment 10: two occurrences in cs_nav_prefs_advanced.xhtml.

Comment 2

[Jens Hatlak (:InvisibleSmiley)]

Of course any changes made here must match the application, i.e. any Help changes for changes from bug 652327 must only land after those changes landed.

Comment 3

[rsx11m]

...which means that there likely would be different versions for the "Tools" menu in comm-central vs. comm-2.0 as any changes there may not go into SM 2.1 due to the string freeze being in effect already.

Comment 4

[rsx11m]

I've noticed that nobody hasn't looked into this yet, thus I'll give it a try to the extent I know (I may not be the best candidate as I rarely use extensions or themes, but we'll see...).

I'd suggest to solve this in two steps: Part I addressing the main label changes (specifically "Add-Ons Manager" which is plural now, and the "Themes" tab was renamed to "Appearance") and cleaning up the respective linking; this should be easy to do and review, but affects 6 files as far as I can tell. Part II would concentrate on the specific description of the Add-Ons Manager in customize_help.xhtml and update it to match the current layout and function; this may need a few iterations, but could be worked on without carrying the Part I changes along with it.

Part I should be doable over the upcoming weekend.

Comment 5

[rsx11m]

Attachment: Part I: main labels and links

Ok, here comes the "easy" part. This patch changes all remaining occurrences of "Add-On Manager" and "Themes Panel" to "Add-Ons Manager" and "Appearance Panel", respectively, and renames the corresponding links throughout the help documents. Nothing else is done at this point, but that should be ready for separate review and check-in while looking into the changes necessary for the content.

This was done by a case-insensitive search for the respective strings over the entire locales/en-US tree, also across line breaks, thus it should have found all occurrences of those strings (I've also searched for "Themes button" but none).

Comment 6

[rsx11m]

Attachment: Part I: main labels and links (v2), pushed (comment #9)

After installing a language pack for testing, I've noticed that the button for the Language panel appears /below/ the Plugins panel, thus I've adjusted the order of panels for this part already. No other changes vs. my initial patch.

Comment 7

[Stefan [:stefanh]]

Comment on attachment 706787 [details] [diff] [review]
Part I: main labels and links (v2), pushed (comment #9)

Looks good - thanks!

Comment 8

[rsx11m]

Thanks - push on trunk for Part I, and please leave open for the second part.

Comment 9

[Stefan [:stefanh]]

Pushed attachment 706787 [details] [diff] [review]:
http://hg.mozilla.org/comm-central/rev/eee5b211537b

Comment 10

[rsx11m]

Attachment: Part II: panel descriptions

This is now the overhaul of customize_help.xhtml for the redesign of the Add-ons Manager, along with some minor changes to the introductory sections. A couple of remarks:

(1a) I've spun off new subsections for "Searching for Add-ons" and "Updating Add-ons" which were previously hidden in the "Get Add-ons" and "Extensions" panel descriptions.

(1b) I'm unable to test the alphabetical index, this function apparently does no longer exist. On the other hand, searching for "panel" brings up those entries twice (my guess is once from the alphabetical index and the other one the "real" entry). Shall I remove the pseudo-duplicates from help-index1.rdf? I've added alphabetical entries for searching_for_add-ons and updating_add-ons to keep it consistent, but on a second thought, those seem to be redundant.

(1c) After renaming "themes panel" to "appearance panel" in help-index1.rdf, this is now moved from "#t" to "#a" for the alphabetical listing, in case those entries are going to stay.
 
(2) I've put longer link-type labels into "es, otherwise they are hard to identify as such and using bold doesn't seem to apply for this generic type of descriptions (at least not done elsewhere in this file).

(3) I'm mentioning Personas now but not with much emphasis on them (i.e., as part of the Themes description without making them qualify as a 5th class of Add-ons). While there are some differences between them and "complete" themes (e.g., no restart required when changing personas), in general they are about appearance and thus show up in that panel like ordinary themes.

(4) Plugins have an "Options" button which doesn't do anything for me for any plugin found, just shows the same dialog as the "More" link. Thus, I haven't documented it as this looks more like a bug to me.

Comment 11

[Stefan [:stefanh]]

I'm a bit behind, but I'll hopefully have time to look at this on Sunday.

Comment 12

[rsx11m]

Sunday sounds good.

Comment 13

[rsx11m]

> (comment #10) [alphabetical index] (1b) ..., searching for "panel" brings
> up those entries twice (...). Shall I remove the pseudo-duplicates from
> help-index1.rdf? I've added alphabetical entries for searching_for_add-ons
> and updating_add-ons to keep it consistent, but on a second thought, those
> seem to be redundant.

Interesting, if I remove those "redundant" alphabetical entries and type something like "languages" or "updating" into the search box, it will no longer find the 2nd-level entries. So, apparently that's not going to work and I'll better leave those entries as they are for now...

Comment 14

[Stefan [:stefanh]]

Comment on attachment 707633 [details] [diff] [review]
Part II: panel descriptions

Thanks a lot for the patch :-)

In general:
a) I looked through the help files and we're using <q> for quotes (there are only 9 "&quot" compared to over 200 <q>), so we should use the tag instead of the entity.
b) There are a bunch of places where you say "click on" (like the one below). We should just "click" things.

-  <li>Quit and restart &brandShortName;.</li>
+  <li>Click on Restart Now which appears in the theme&apos;s entry.</li>
 </ol>

Perhaps we should tell the user that he/she is about to restart before we tell him/her to click Restart Now.

"Restart &brandShortName; by clicking Restart Now in the Themes entry" (quotes around Restart Now)


-    Theme, but you can add more to fit your style.</li>
+    Theme, but you can add more to fit your style. <strong>Personas</strong>
+    are light-weight themes which, in contrast to the &quot;complete&quot;
+    themes, change &brandShortName;&apos;s background only but do not have any
+    effect on the style of buttons and other elements.</li>
I would make it more simple here: Perhaps something like this:
"Personas are light-weight themes that only change the background of the user interface."


 <p>There are a number of ways to install Add-ons:</p>
 
 <ul>
-  <li>By clicking a link for an Add-on on a web page. This will trigger
-    a &brandShortName; dialog asking you to confirm or cancel the
+  <li>By clicking a link or button for an Add-on on a web page. This will

"or a button"

+    trigger a &brandShortName; dialog asking you to confirm or cancel the
     installation, with the Install button disabled for some seconds in
-    order to avoid accidentally clicking it just as the dialog shows up.
-    
-    <p><strong>Note</strong>: As an additonal security measure,
-      &brandShortName; only allows installing Add-ons from a list of permitted
-      websites in the <a
-      href="cs_nav_prefs_advanced.xhtml#software_installation">Software
-      Installation preferences panel</a>.</p>
-  </li>
+    order to avoid accidentally clicking it just as the dialog shows up.</li>
   <li>By opening a previously saved Add-on package, just like you open a
     regular file that you previously saved on your hard drive: Select Open file
     from the File menu, or press <span class="mac"><kbd>Cmd</kbd></span><span
-    class="noMac"><kbd>Ctrl</kbd></span>+<kbd>O</kbd>.</li>
-  <li>By using the Get Add-ons panel in the Add-ons Manager or clicking the
-    Install button in any of the panels in the Add-ons Manager.</li>
+    class="noMac"><kbd>Ctrl</kbd></span>+<kbd>O</kbd>; you can also use the
+    &quot;Install Add-on from File&quot; function in the Tools menu of the

Perhaps "you can also open the Tools menu in the Add-ons Manager and select <q>Install Add-on from File</q> 
+    Add-Ons Manager, or just drag-and-drop the installer file into it.</li>
Maybe "into the Add-ons Manager window."?


+<h4 id="searching_for_add-ons">Searching for Add-ons</h4>
+
+<p>The Search panel in the Add-ons Manager is initially not visible but opens
+  as soon as a search is performed. It gives you the option to search all
+  available Mozilla Add-ons directly from the Add-ons Manager and to install
+  them as desired . After
+  <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
+  find the Search box in the upper-right corner of the Add-ons Manager.
+  There, you can perform the following actions:
+</p>

I don't think we should be too specific about the position of the search box (think rtl for example). Perhaps we should also go straight to the search section instead and then just mention that the search panel becomes visible. The search panel feels a bit just like a results view from where you can sort your results.

It would be good with a new patch addressing my comments - then I can have another look.

Comment 15

[rsx11m]

Attachment: Part II: panel descriptions (v2)

All done, a couple of responses to your comment #14:

> I would make it more simple here: Perhaps something like this:
> "Personas are light-weight themes that only change the background of the
> user interface."

I've kept the "complete" theme given that this term is used later on in the buttons of the "Get Add-Ons" panel and were confusing to me in the beginning.

> +    Add-Ons Manager, or just drag-and-drop the installer file into it.</li>
> Maybe "into the Add-ons Manager window."?

It's actually "tab or window" depending on your "Link Behavior" settings.

> I don't think we should be too specific about the position of the search box
> (think rtl for example). Perhaps we should also go straight to the search
> section instead and then just mention that the search panel becomes visible.
> The search panel feels a bit just like a results view from where you can
> sort your results.

Ok, I've moved mentioning of the Search panel opening to the location after entering and performing the search. I could make it even shorter by just saying "After accessing the Add-ons Manager, find its Search box." to reduce the number of "Add-ons Manager" uses in that section.

Comment 16

[rsx11m]

Attachment: Part II: panel descriptions (v2b)

> (comment #15) "After accessing the Add-ons Manager, find its Search box."

Let's go with this, I like the less wordy version better than "After accessing the Add-ons Manager, find the Search box in the Add-ons Manager."

The only other changes relative to attachment 709501 [details] [diff] [review] are some white-space cleanups in two locations for the plugin description.

Comment 17

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 709545 [details] [diff] [review]
Part II: panel descriptions (v2b)

Review of attachment 709545 [details] [diff] [review]:
-----------------------------------------------------------------

::: suite/locales/en-US/chrome/common/help/customize_help.xhtml
@@ +1094,5 @@
>      regular file that you previously saved on your hard drive: Select Open file
>      from the File menu, or press <span class="mac"><kbd>Cmd</kbd></span><span
> +    class="noMac"><kbd>Ctrl</kbd></span>+<kbd>O</kbd>; you can also open the
> +    Tools menu in the Add-Ons Manager and select <q>Install Add-on from
> +    File</q>, or just drag-and-drop the installer file into the Add-Ons

Drive-by nit: "Add-ons" (2x)

Comment 18

[rsx11m]

Attachment: Part II: panel descriptions (v2c)

Oops, taken care of. No further occurrences.

Comment 19

[Stefan [:stefanh]]

Sorry for the delay (too much things IRL atm), but I'll look at it over the weekend (most likely they'll be a few more iterations before we're done here).

Comment 20

[rsx11m]

No problem, just let me know what you think (the more specific the better) and I'll have a new patch up by next weekend.

Comment 21

[Stefan [:stefanh]]

Comment on attachment 709887 [details] [diff] [review]
Part II: panel descriptions (v2c)

Looks very good. Just a few more iterations (I will probably find a few more minor things during the next round):


> <div class="contentsBox">In this section:
>   <ul>
>     <li><a href="#navigation_toolbar">Navigation Toolbar</a></li>
>@@ -1044,264 +1049,323 @@
>   <li><strong>Extensions</strong>: This type of Add-on either changes the way
>     &brandShortName; behaves or adds new features to it. For instance, there
>     are extensions that provide you with weather forecasts, that add a
>     full-featured FTP client, or that block advertisements in web pages. Some
>     extensions are designed to work only with specific websites.</li>
>   <li><strong>Themes</strong>: Themes change the appearance and design of
>     &brandShortName;, but don&apos;t add or change features. They act as a
>     skin. &brandShortName; ships with two themes, Default Theme and Modern
>-    Theme, but you can add more to fit your style.</li>
>+    Theme, but you can add more to fit your style. <strong>Personas</strong>
>+    are light-weight themes which, in contrast to the <q>complete</q> themes,

I don't think we should have quotes around "complete". I get the idea, but I think it will be a bit confusing since we're using quotes to indicate something in the UI. Regarding the <q>:s, at some time in the future, we should consider styling them.

>+    change the background of the user interface only.</li>
>+  <li><strong>Plugins</strong>: Plugins act as connectors between
>+    &brandShortName; and other programs. They enable you to see special
>+    content (like Flash movies, or Adobe PDF documents) directly inside the
>+    &brandShortName; browser window, instead of opening the target program
>+    in a separate window.</li>
>   <li><strong>Languages</strong>: While you can download &brandShortName; in
>     a number of languages, you may add additional languages to it in the form
>     of language packs. This way, different users may use &brandShortName; in
>     their own language without having to install the program for everyone.
>     This is specially useful if you are going to install &brandShortName; on a
>     computer that is shared by different users in, for example, a computer lab.
> 
>     <p><strong>Note</strong>: Language packs only change the user interface
>       language. Web pages, messages, newsgroup and news &amp; blog posts will
>       still be shown in the original language in which they were written.</p>
>   </li>
>-  <li><strong>Plugins</strong>: Plugins act as connectors between
>-    &brandShortName; and other programs. They enable you to see special content
>-    (like Flash movies, or Adobe PDF documents) directly inside the
>-    &brandShortName; browser window, instead of opening the target program in a
>-    separate window.</li>
> </ul>
> 
> <p>Add-ons always come as packages. Each Add-on is a single file with the XPI
>   extension, except in the case of plugins which usually are binaries specific
>   to the target operating system.</p>
> 
> <p>[<a href="#add-ons">Return to beginning of section</a>]</p>
> 
> <h3 id="installing_add-ons">Installing Add-ons</h3>
> 
> <p>There are a number of ways to install Add-ons:</p>
> 
> <ul>
>-  <li>By clicking a link for an Add-on on a web page. This will trigger
>-    a &brandShortName; dialog asking you to confirm or cancel the
>+  <li>By clicking a link or a button for an Add-on on a web page. This will
>+    trigger a &brandShortName; dialog asking you to confirm or cancel the
>     installation, with the Install button disabled for some seconds in
>-    order to avoid accidentally clicking it just as the dialog shows up.
>-    
>-    <p><strong>Note</strong>: As an additonal security measure,
>-      &brandShortName; only allows installing Add-ons from a list of permitted
>-      websites in the <a
>-      href="cs_nav_prefs_advanced.xhtml#software_installation">Software
>-      Installation preferences panel</a>.</p>
>-  </li>
>+    order to avoid accidentally clicking it just as the dialog shows up.</li>
>   <li>By opening a previously saved Add-on package, just like you open a
>     regular file that you previously saved on your hard drive: Select Open file
>     from the File menu, or press <span class="mac"><kbd>Cmd</kbd></span><span
>-    class="noMac"><kbd>Ctrl</kbd></span>+<kbd>O</kbd>.</li>
>-  <li>By using the Get Add-ons panel in the Add-ons Manager or clicking the
>-    Install button in any of the panels in the Add-ons Manager.</li>
>+    class="noMac"><kbd>Ctrl</kbd></span>+<kbd>O</kbd>; you can also open the
>+    Tools menu in the Add-ons Manager and select <q>Install Add-on from

We should probably have "(next to the search box)" in order to not confuse with the main Tools menu.

>+    File</q>, or just drag-and-drop the installer file into the Add-ons
>+    Manager tab or window.</li>
>+  <li>By using the Search functionality or the Get Add-ons panel of the
>+    Add-ons Manager, as described in the next section.</li>
> </ul>
> 
>-<p><strong>Note</strong>: Plugins are usually installed as a separate program
>-  while &brandShortName; is closed so both the external program and the
>-  corresponding plugin for &brandShortName; get installed correctly.</p>
>+<p><strong>Notes</strong>:</p>
>+<ul>
>+  <li>For security, &brandShortName; only allows installing Add-ons from
>+    a list of permitted websites in the
>+    <a href="cs_nav_prefs_advanced.xhtml#software_installation">Software
>+    Installation preferences panel</a>.</li>
>+  <li>Also, if you unchecked <q>Allow websites to install add-ons and
>+    updates</q> there, you will be prompted to enable that function before
>+    anything else happens. This is <em>not</em> a temporary change, you would
>+    have to uncheck that box again to disallow installations and updates in
>+    the future.</li>
>+  <li>Plugins are usually installed as a separate program while
>+    &brandShortName; is closed so both the external program and the
>+    corresponding plugin for &brandShortName; get installed correctly.</li>
>+</ul>
> 
> <p>[<a href="#add-ons">Return to beginning of section</a>]</p>
> 
> <h3 id="using_the_add-ons_manager">Using the Add-ons Manager</h3>
> 
> <p>The Add-ons Manager enables you to install and uninstall Add-ons, enable and
>   disable them and, in some cases, set preferences for them.</p>
>   
> <p id="accessing_the_add-ons_manager">To access the Add-ons Manager, follow any
>   of these steps:</p>
> 
> <ul>
>   <li>Open the Tools menu, then select Add-ons Manager.</li>
>   <li>Open the <span class="mac">&brandShortName;</span><span
>     class="noMac">Edit</span> menu and choose Preferences, expand the Advanced
>-    category and click Software Installation.</li>
>+    category, click Software Installation, then Manage Add-ons.</li>
> </ul>
> 
> <div class="contentsBox">In this section:
>   <ul>
>+    <li><a href="#searching_for_add-ons">Searching for Add-ons</a></li>
>     <li><a href="#the_get_add-ons_panel">The Get Add-ons panel</a></li>
>     <li><a href="#the_extensions_panel">The Extensions panel</a></li>
>     <li><a href="#the_appearance_panel">The Appearance panel</a></li>
>     <li><a href="#the_plugins_panel">The Plugins panel</a></li>
>     <li><a href="#the_languages_panel">The Languages panel</a></li>
>+    <li><a href="#updating_add-ons">Updating Add-ons</a></li>
>   </ul>
> </div>
> 
>+<h4 id="searching_for_add-ons">Searching for Add-ons</h4>
>+
>+<p>The Search panel in the Add-ons Manager gives you the option to search all
>+  available Mozilla Add-ons directly from the Add-ons Manager and to install
>+  them as desired. After <a href="#accessing_the_add-ons_manager">accessing
>+  the Add-ons Manager</a>, find its Search box. There, you can perform the
>+  following actions:
>+</p>

I still think this is a bit confusing. The problem is that it's not the search panel that gives you the option to search, it's the search box itself and we don't have a search panel until you have started searching for something. We also can't do all the things below in the actual search box.

I'm tempted to skip the whole intro here and just go straight to the action.

>+
>+<ul>
>+  <li>To search for Add-ons based on name, description or tags, type a word
>+    or phrase into the Search box.

and press 

>+    Press <span class="mac"><kbd>Return</kbd></span><span
>+    class="noMac"><kbd>Enter</kbd></span>to open the Search panel, showing
>+    a list of matching Add-ons.

Here you could stop after the last </span>, adding a ".". Then we could say something like: "The Search panel will open and display a list of results."

>+
>+    <p><strong>Note</strong>: Add-ons that are already installed or
>+      incompatible with your current version of &brandShortName; will not be
>+      displayed in the list of search results.</p>
>+  </li>

Now, we could re-write the section below - it's things you can do once you've got a result from the above search (in the recently opened Search panel).

Something like this, perhaps (you get the idea - note also that the note above will not be needed):

"By default, the search panel will show you a list of available Add-ons that are compatible with your current version of &brandShortName;. To get additional information about a specific Add-on in the list, click <q>More</q>. To install an Add-on in the list, click the Install button."

>+  <li>Click More to get additional information on a specific Add-on.</li>
>+  <li>Click the Install button in an entry to install this Add-on.</li>
>+</ul>

You won't need the above <li>:s with my suggestion. It might be an overkill, but you could mention that once the search panel is visible, you can sort the results and also search your installed Add-ons.

>+
>+<p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
>+
> <h4 id="the_get_add-ons_panel">The Get Add-ons panel</h4>
> 
> <p>The Get Add-ons panel in the Add-ons Manager uses web services provided by
>   the Mozilla Add-ons website to present a list of recommended Add-ons, as
>-  well as giving you the option to search all available Mozilla Add-ons
>-  directly from the Add-ons Manager. After
>+  well as giving you the option to browse the available Mozilla Add-ons. After
>   <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
>   click the Get Add-ons button to show the Get Add-ons panel. There, you can
>   perform the following actions:</p>
> 
> <ul>
>-  <li>To search for Add-ons based on name, description or tags, use the
>-    Search box. Type a word or phrase and press <span
>-    class="mac"><kbd>Return</kbd></span><span
>-    class="noMac"><kbd>Enter</kbd></span>. You will get a list of matching
>-    Add-ons. To clear the search box terms and the result list, click the
>-    icon inside the search box.
>-
>-    <p><strong>Note</strong>: Add-ons that are already installed or
>-      incompatible with your current version of &brandShortName; will not be
>-      displayed in the list of search results.</p>
>+  <li>To get more information about one of the recommended Add-ons in the list
>+    displayed by default, click that entry. The entry will expand to use the
>+    full tab, showing screenshots, a description of the Add-on, and reviews
>+    as available. You will also be able to directly install the Add-on by
>+    clicking the Add to &brandShortName; button inside the expanded entry.
>+    <p><strong>Note</strong>: If you disallowed websites to install add-ons
>+      and updates in the <a
>+      href="cs_nav_prefs_advanced.xhtml#software_installation">Software
>+      Installation preferences panel</a>, you will be prompted to enable
>+      that function before anything else happens. This is <em>not</em> a
>+      temporary change, you would have to uncheck that box again to
>+      disallow installations and updates in the future.</p>
>   </li>
>   <li>To open the Mozilla Add-ons website in a new browser window (or a new
>-    browser tab, depending on your preferences), click Browse All Add-ons.</li>
>-  <li>To get more information about one of the recommended Add-ons in the list
>-    displayed by default, click the entry. The entry will expand, displaying
>-    a larger image, a full description of the Add-on, and an indication of the
>-    Add-on type (extension, theme, etc.). You will also be able to install the
>-    Add-on by clicking the Add to &brandShortName; button inside the
>-    expanded entry.</li>
>-  <li>To display the full list of recommended Add-ons for &brandShortName; in a
>-    new browser window (or a new browser tab, depending on your preferences),
>-    scroll down the recommended Add-ons list until you see the See All
>-    Recommended Add-ons link.</li>
>+    browser tab, depending on your preferences), scroll down the Get Add-ons
>+    panel and click <q>Browse all Add-ons</q>. This will start with the
>+    Featured Extensions list for &brandShortName;. Use <q>See all complete
>+    themes</q> instead to get the Most Popular Complete Themes page.</li>

Hmm, I don't see "See all complete themes". It's probably best to not refer to links/titles on the actual web site (it might change)

>+  <li>Personalized Add-on recommendations require a list of your currently
>+    installed Add-ons to be sent to the Mozilla Add-ons website. If you have
>+    privacy concerns, this function can be switched off in the
>+    <a href="cs_nav_prefs_advanced.xhtml#software_installation">Software
>+    Installation preferences panel</a>.</li>
> </ul>

The last <li> should be a note. This is not an action you can perform.

> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_extensions_panel">The Extensions panel</h4>
> 
> <p>The Extensions panel in the Add-ons Manager lists the installed extensions.
>   After <a href="#accessing_the_add-ons_manager">accessing the Add-ons
>   Manager</a>, click the Extensions button to show the Extensions panel. There,
>   you can perform the following actions:</p>
> 
> <ul>
>-  <li>To get more information about any of the installed extensions, click the
>-    entry in the list. The entry will expand and show the full description of
>-    the extension.
>+  <li>To get more information about any of the installed extensions, click
>+    More for the entry in the list. The entry will expand into the full tab
>+    and show the description of the extension along with its update options.
> 
>     <p><strong>Note</strong>: Disabled extensions will appear greyed out.
>       Incompatible extensions will appear greyed out, since they are also
>       disabled, and with a forbidden sign over the extension icon (incompatible
>       extensions are those which define themselves as not compatible for the
>       version of &brandShortName; you are using).</p>
>   </li>
>-  <li>To access preferences of an extension (if the extension features a
>-    preferences panel), click the entry corresponding to the desired extension,
>-    then click the Preferences button.
>+  <li>To access options of an extension (if the extension features a
>+    preferences panel), click the Options button of the entry corresponding
>+    to the desired extension.

"for the entry"
> 
>     <p><strong>Note</strong>: If the extension does not feature a preferences
>-      panel, the Preferences button will be disabled. You can&apos;t access
>+      panel, the Options button will be hidden. You can&apos;t access
>       preferences of disabled or incompatible extensions.</p>
>   </li>
>-  <li>To disable an extension, click the entry corresponding to the desired
>-    extension, then click the Disable button. An info bar will appear to remind
>-    you that changes will apply once you restart &brandShortName;. The info bar
>-    features a Restart &brandShortName; button.</li>
>-  <li>To enable an extension, click the entry corresponding to the desired
>-    extension, then click the Enable button. An info bar will appear to remind
>-    you that changes will apply once you restart &brandShortName;. The info bar
>-    features a Restart &brandShortName; button.</li>
>-  <li>To uninstall an extension, click the entry corresponding to the
>-    desired extension, then click the Uninstall button. An info bar will
>-    appear to remind you that changes will apply once you restart
>-    &brandShortName;. The info bar features a Restart &brandShortName;
>-    button.</li>
>-  <li>To find updates for any extension in the list (including those marked as
>-    incompatible), click the Find Updates button at the bottom of the
>-    Add-ons Manager.
>-
>-    <p>If updates are found, they will be displayed in a new panel. In the
>-      panel, you can choose what extensions you want to update and then use the
>-      Install Updates button to retrieve updated Add-ons. Once downloaded, you
>-      will need to restart &brandShortName; to apply the updates.</p>
>-  </li>
>+  <li>To disable an extension, click the Disable button of the entry

"for the entry"

>+    corresponding to the desired extension. An info bar may appear if
>+    the changes will apply only once you restart &brandShortName;.
>+    Click Restart Now if that&apos;s the case.</li>

I think we should leave the restart to the user, it's enough to say that the info bar has a restart button (or just omit the whole text about the restart button). Why "may appear" and not keeping the old text?

>+  <li>To enable an extension, click the Enable button of the entry

"for the entry"

>+    corresponding to the desired extension. An info bar may appear if
>+    the changes will apply only once you restart &brandShortName;.
>+    Click Restart Now if that&apos;s the case.</li>
>+  <li>To uninstall an extension, click the Remove button of the entry

"for the entry"

>+    corresponding to the desired extension. An info bar may appear if
>+    the changes will apply only once you restart &brandShortName;.
>+    Click Restart Now if that&apos;s the case.</li>
> </ul>
> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_appearance_panel">The Appearance panel</h4>
> 
> <p>The Appearance panel in the Add-ons Manager lists the installed themes. After
>   <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
>   click the Appearance button to show the Appearance panel. There, you can
>   perform the following actions:</p>
> 
> <ul>
>-  <li>To get more information and a preview on any of the installed themes,
>-    click an entry in the list. The entry will expand and show the full
>-    description of the theme, along with a preview in the right side of the
>-    Add-ons Manager dialog (you may need to resize the dialog to properly see
>-    the preview pane).</li>
>-  <li>To use a theme, click the entry corresponding to the desired theme, then
>-    click the Use Theme button. An info bar will appear to remind you that
>-    changes will apply once you restart &brandShortName;. The info bar features
>-    a Restart &brandShortName; button.
>+  <li>To get more information about any of the installed themes, click More

<q>More</q>

>+    for the entry in the list. The entry will expand into the full tab and

>+    show the description of the theme along with its version information.</li>
>+  <li>To use a theme, click the Enable button of the entry corresponding

"for the entry"

>+    to the desired theme. An info bar may appear if the changes will apply
>+    only once you restart &brandShortName;. Click Restart Now if that&apos;s
>+    the case.

See earlier comment regarding the restart and the "may".


>     
>-    <p><strong>Note</strong>: Contrary to extensions, you only can use one
>+    <p><strong>Note</strong>: Contrary to extensions, you can use only one
>     theme at a time.</p>
>   </li>
>-  <li>To uninstall a theme, click the entry corresponding to the desired theme,
>-    then click the Uninstall button. An info bar will appear to remind
>-    you that changes will apply once you restart &brandShortName;. The info bar
>-    features a Restart &brandShortName; button.</li>
>+  <li>To uninstall a theme, click the Remove button of the entry corresponding

"for the entry"

>+    to the desired theme. An info bar may appear if the changes will apply
>+    only once you restart &brandShortName;. Click Restart Now if that&apos;s
>+    the case.</li>

See earlier comment regarding the restart and the "may".

> </ul>
> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_plugins_panel">The Plugins panel</h4>
> 
>-<p>The Plugins panel in the Add-ons Manager lists the installed Add-ons of type
>-  Plugin. After <a href="#accessing_the_add-ons_manager">accessing the Add-ons
>-  Manager</a>, click the Plugins button to show the Plugins panel. There, you
>-  can perform the following actions:</p>
>+<p>The Plugins panel in the Add-ons Manager lists the plugins found. After
>+  <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
>+  click the Plugins button to show the Plugins panel. There, you can perform
>+  the following actions:</p>
> 
> <ul>
>-  <li>To disable a plugin, click the entry corresponding to the desired plugin,
>-    then click the Disable button.</li>
>-  <li>To enable a plugin, click the entry corresponding to the desired plugin,
>-    then click the Enable button.</li>
>+  <li>To get more information about any of the plugins found, click More
>+    for the entry in the list. The entry will expand into the full tab and show
>+    the description of the plugin along with its version information.</li>
>+  <li>Info bars may appear for any plugins which are determined to be outdated,
>+    incompatible, or blocked for security reasons.</li>
>+  <li>Click <q>Check to see if your plugins are up to date</q> to open a new
>+    tab or window connecting to a Mozilla website to check for status and
>+    update information on all of your enabled plugins.</li>
>+  <li>To disable a plugin, click the Disable button of the entry corresponding
>+    to the desired plugin.</li>

"for the entry"

>+  <li>To enable a plugin, click the Enable button of the entry corresponding

"for the entry"

>+    to the desired plugin.</li>
> </ul>
> 
> <p><strong>Note</strong>: Contrary to other types of Add-ons, enabling and
>   disabling plugins doesn&apos;t require restarting &brandShortName;.</p>
> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_languages_panel">The Languages panel</h4>
> 
>-<p>The Languages panel in the Add-ons Manager lists the installed Language
>-  Packs. This panel only appears if you have installed a Language Pack.</p>
>+<p>The Languages panel in the Add-ons Manager lists the installed language
>+  packs. This panel only appears if you have installed a language pack.</p>
> 
> <p>After <a href="#accessing_the_add-ons_manager">accessing the Add-ons
>   Manager</a>, click the Languages button to show the Languages panel. There,
>   you can perform the following actions:</p>
> 
> <ul>
>-  <li>To disable a language pack, click the entry corresponding to the desired
>-    language pack, then click the Disable button. An info bar will appear to
>-    remind you that changes will apply once you restart &brandShortName;. The
>-    info bar features a Restart &brandShortName; button.</li>
>-  <li>To enable a language pack, click the entry corresponding to the desired
>-    language pack, then click the Enable button. An info bar will appear to
>-    remind you that changes will apply once you restart &brandShortName;. The
>-    info bar features a Restart &brandShortName; button.</li>
>-  <li>To uninstall a language pack, click the entry corresponding to the
>-    desired language pack, then click the Uninstall button. An info bar will
>-    appear to remind you that changes will apply once you restart
>-    &brandShortName;. The info bar features a Restart &brandShortName;
>-    button.</li>
>+  <li>To get more information about any of the language packs, click More
>+    for the entry in the list. The entry will expand into the full tab and show
>+    the description of the language pack along with its update options.</li>
>+  <li>To disable a language pack, click the Disable button of the entry

"for the entry"

>+    corresponding to the desired language pack.</li>
>+  <li>To enable a language pack, click the Enable button of the entry

"for the entry"

>+    corresponding to the desired language pack.</li>
>+  <li>To uninstall a language pack, click the Remove button of the entry

"for the entry"

>+    corresponding to the desired language pack.</li>
> </ul>
> 
> <p><strong>Note</strong>: Enabling a language pack in the Language panel
>   doesn&apos;t change the language shown in &brandShortName;&apos;s user
>   interface, it only makes the language available for selection in the
>   <a href="cs_nav_prefs_appearance.xhtml#appearance">Appearance Preferences
>-  panel</a>.</p>
>+  panel</a>. You have to quit and restart &brandShortName; after making
>+  any changes in the selected language pack.</p>
>+
>+<p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
>+
>+<h4 id="updating_add-ons">Updating Add-ons</h4>
>+
>+<p>Updates are by default performed automatically for any Add-ons installed
>+  through the Search or Get Add-ons panels and for which such updates are
>+  offered through the Mozilla Add-ons website.The global settings can be found

(space before "The")
If the key for them to be automatic is that they're offered through the Mozilla Add-ons website, you want to change "and for which" to "if".


>+  in the <a href="cs_nav_prefs_advanced.xhtml#software_installation">Software
>+  Installation preferences panel</a>. You can override those for individual
>+  Add-ons by clicking on More and then selecting the desired option.

"clicking <q>More</q>"

>+</p>
>+
>+<p>Update functions are also offered in the Add-ons Manager&apos;s Tools menu,
>+  which is the icon left of the search bar and not to be mixed up with the
>+  general Tools menu:</p>

"Update functions are also offered in the Add-ons Manager&apos;s Tools menu, found next to the search box." (skip the "not to be mixed up" part)

Comment 22

[rsx11m]

Attachment: Part II: panel descriptions (v3)

All items addressed, below some comments or the more tricky issues.

(In reply to Stefan [:stefanh] from comment #21)
> I don't think we should have quotes around "complete". I get the idea, but I
> think it will be a bit confusing since we're using quotes to indicate
> something in the UI.

That's ok, also given that I've removed mentioning of the "complete themes" link from the Get Add-ons web page. The "More" and "Restart Now" links have been consequently put into <q> to ensure that they are recognized as links.

> >+<p>The Search panel in the Add-ons Manager gives you the option to search all
> >+  available Mozilla Add-ons directly from the Add-ons Manager and to install
> >+  them as desired. After <a href="#accessing_the_add-ons_manager">accessing
> >+  the Add-ons Manager</a>, find its Search box. There, you can perform the
> >+  following actions:
> >+</p>
> 
> I still think this is a bit confusing. The problem is that it's not the
> search panel that gives you the option to search, it's the search box itself
> and we don't have a search panel until you have started searching for
> something. We also can't do all the things below in the actual search box.
> 
> I'm tempted to skip the whole intro here and just go straight to the action.

Ok, I didn't remove the intro though (given that we have one everywhere else) but made it short and rather generic, then jumping into the action items.

> >+
> >+<ul>
> >+  <li>To search for Add-ons based on name, description or tags, type a word
> >+    or phrase into the Search box.
> 
> and press 
> 
> >+    Press <span class="mac"><kbd>Return</kbd></span><span
> >+    class="noMac"><kbd>Enter</kbd></span>to open the Search panel, showing
> >+    a list of matching Add-ons.
> 
> Here you could stop after the last </span>, adding a ".". Then we could say
> something like: "The Search panel will open and display a list of results."
> 
> >+
> >+    <p><strong>Note</strong>: Add-ons that are already installed or
> >+      incompatible with your current version of &brandShortName; will not be
> >+      displayed in the list of search results.</p>
> >+  </li>
> 
> Now, we could re-write the section below - it's things you can do once
> you've got a result from the above search (in the recently opened Search
> panel).
> 
> Something like this, perhaps (you get the idea - note also that the note
> above will not be needed):
> 
> "By default, the search panel will show you a list of available Add-ons that
> are compatible with your current version of &brandShortName;. To get
> additional information about a specific Add-on in the list, click
> <q>More</q>. To install an Add-on in the list, click the Install button."
> 
> >+  <li>Click More to get additional information on a specific Add-on.</li>
> >+  <li>Click the Install button in an entry to install this Add-on.</li>
> >+</ul>
> 
> You won't need the above <li>:s with my suggestion. It might be an overkill,
> but you could mention that once the search panel is visible, you can sort
> the results and also search your installed Add-ons.

I've come up with some hybrid. On one hand, I'd agree with your order of description; but, on the other hand, I'd like to keep the bullet-list style as it is easier to read than a continuous text and makes it easier to identify the individual actions and discussion points. This is hopefully ok, otherwise I'll do it your way.

> >+    browser tab, depending on your preferences), scroll down the Get Add-ons
> >+    panel and click <q>Browse all Add-ons</q>. This will start with the
> >+    Featured Extensions list for &brandShortName;. Use <q>See all complete
> >+    themes</q> instead to get the Most Popular Complete Themes page.</li>
> 
> Hmm, I don't see "See all complete themes". It's probably best to not refer
> to links/titles on the actual web site (it might change)

It shows up for me with both release and development versions, but for WINNT. Maybe it's Mac specific?

Anyway, as you are correct that this is content on the AMO web site, I've removed the specific links and replaced the text with a more generic description.

> The last <li> should be a note. This is not an action you can perform.

Done.

> >+    corresponding to the desired extension. An info bar may appear if
> >+    the changes will apply only once you restart &brandShortName;.
> >+    Click Restart Now if that&apos;s the case.</li>
> 
> I think we should leave the restart to the user, it's enough to say that the
> info bar has a restart button (or just omit the whole text about the restart
> button). Why "may appear" and not keeping the old text?

With the old Add-ons Manager, restarting was always necessary whereas newer concepts (like restartless add-ons or personas) don't require a restart in all cases. Thus, I've tried to phrase that more conditionally, where the "may" in addition to the following "if" clause is overdoing it. I've removed it and made the description of the "Restart Now" link more sound like an optional task.

> >+<p>Updates are by default performed automatically for any Add-ons installed
> >+  through the Search or Get Add-ons panels and for which such updates are
> >+  offered through the Mozilla Add-ons website. [...]
> If the key for them to be automatic is that they're offered through the
> Mozilla Add-ons website, you want to change "and for which" to "if".

That was my understanding, though I wasn't sure if there aren't any other mechanisms an add-on could use to update itself automatically even if it's not listed officially on AMO.

Comment 23

[Stefan [:stefanh]]

Comment on attachment 714342 [details] [diff] [review]
Part II: panel descriptions (v3)

Just a few things left (hence the f+):
 
>+<h4 id="searching_for_add-ons">Searching for Add-ons</h4>
>+
>+<p>After <a href="#accessing_the_add-ons_manager">accessing the Add-ons
>+  Manager</a>, you can search all available Mozilla Add-ons directly from
>+  the Add-ons Manager and install them as desired:</p>
>+
>+<ul>
>+  <li>To search for Add-ons based on name, description or tags, type a
>+    word or phrase into the Search box and press
>+    <span class="mac"><kbd>Return</kbd></span><span
>+    class="noMac"><kbd>Enter</kbd></span>.</li>
>+  <li>The search panel will open and display a list of matching Add-ons
>+    that are compatible with your current version of &brandShortName;.</li>
>+  <li>Once the search panel is visible, you can sort the results and also
>+    search your installed Add-ons.</li>
>+  <li>To get additional information about a specific Add-on in the list,
>+    click <q>More</q> for that entry.</li>
>+  <li>To install an Add-on in the list, click its Install button.</li>
>+</ul>
>+

I completely agree with the hybrid version here, but I think the second and third <li> is bit out of context. They're not as straight-forward as the other ones (one is purely descriptional, the other informs you that you _can_ do things). I think we should put the text from those 2 into the first <li> (might need some minor re-write). That would also make the last 2 <li>:s more logical. What do you think?

>+<p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
>+
> <h4 id="the_get_add-ons_panel">The Get Add-ons panel</h4>
> 
> <p>The Get Add-ons panel in the Add-ons Manager uses web services provided by
>   the Mozilla Add-ons website to present a list of recommended Add-ons, as
>-  well as giving you the option to search all available Mozilla Add-ons
>-  directly from the Add-ons Manager. After
>+  well as giving you the option to browse the available Mozilla Add-ons. After
>   <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
>   click the Get Add-ons button to show the Get Add-ons panel. There, you can
>   perform the following actions:</p>
> 
> <ul>
>-  <li>To search for Add-ons based on name, description or tags, use the
>-    Search box. Type a word or phrase and press <span
>-    class="mac"><kbd>Return</kbd></span><span
>-    class="noMac"><kbd>Enter</kbd></span>. You will get a list of matching
>-    Add-ons. To clear the search box terms and the result list, click the
>-    icon inside the search box.
>+  <li>To get more information about one of the recommended Add-ons in the list
>+    displayed by default, click that entry. The entry will expand to use the
>+    full tab, showing screenshots, a description of the Add-on, and reviews
>+    as available. You will also be able to directly install the Add-on by
>+    clicking the Add to &brandShortName; button inside the expanded entry.
>+    <p><strong>Note</strong>: If you disallowed websites to install add-ons
>+      and updates in the <a
>+      href="cs_nav_prefs_advanced.xhtml#software_installation">Software
>+      Installation preferences panel</a>, you will be prompted to enable
>+      that function before anything else happens. This is <em>not</em> a
>+      temporary change, you would have to uncheck that box again to
>+      disallow installations and updates in the future.</p>
>+  </li>
>+  <li>The Get Add-ons panel also allows you to open the Mozilla Add-ons website
>+    in a new browser window (or a new browser tab, depending on your preference
>+    settingss) to browse extensions and themes.</li>
>+</ul>

The "There, you can perform the following actions:" in the intro doesn't really fit with the last <li> here. Otoh, it would look odd with just one <li>. So, what if we removed the "There, you can perform the following actions:"?

> 
>-    <p><strong>Note</strong>: Add-ons that are already installed or
>-      incompatible with your current version of &brandShortName; will not be
>-      displayed in the list of search results.</p>
>-  </li>
>-  <li>To open the Mozilla Add-ons website in a new browser window (or a new
>-    browser tab, depending on your preferences), click Browse All Add-ons.</li>
>-  <li>To get more information about one of the recommended Add-ons in the list
>-    displayed by default, click the entry. The entry will expand, displaying
>-    a larger image, a full description of the Add-on, and an indication of the
>-    Add-on type (extension, theme, etc.). You will also be able to install the
>-    Add-on by clicking the Add to &brandShortName; button inside the
>-    expanded entry.</li>
>-  <li>To display the full list of recommended Add-ons for &brandShortName; in a
>-    new browser window (or a new browser tab, depending on your preferences),
>-    scroll down the recommended Add-ons list until you see the See All
>-    Recommended Add-ons link.</li>
>-</ul>
>+<p><strong>Note</strong>: Personalized Add-on recommendations require a list of
>+  your currently installed Add-ons to be sent to the Mozilla Add-ons website.
>+  If you have privacy concerns, this function can be switched off in the
>+  <a href="cs_nav_prefs_advanced.xhtml#software_installation">Software
>+  Installation preferences panel</a>.</p>
> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_extensions_panel">The Extensions panel</h4>
> 
> <p>The Extensions panel in the Add-ons Manager lists the installed extensions.
>   After <a href="#accessing_the_add-ons_manager">accessing the Add-ons
>   Manager</a>, click the Extensions button to show the Extensions panel. There,
>   you can perform the following actions:</p>
> 
> <ul>
>-  <li>To get more information about any of the installed extensions, click the
>-    entry in the list. The entry will expand and show the full description of
>-    the extension.
>+  <li>To get more information about any of the installed extensions, click
>+    <q>More</q> for the entry in the list. The entry will expand into the full
>+    tab and show the description of the extension along with its update
>+    options.
> 
>     <p><strong>Note</strong>: Disabled extensions will appear greyed out.
>       Incompatible extensions will appear greyed out, since they are also
>       disabled, and with a forbidden sign over the extension icon (incompatible
>       extensions are those which define themselves as not compatible for the
>       version of &brandShortName; you are using).</p>
>   </li>
>-  <li>To access preferences of an extension (if the extension features a
>-    preferences panel), click the entry corresponding to the desired extension,
>-    then click the Preferences button.
>+  <li>To access options of an extension (if the extension features a
>+    preferences panel), click the Options button for the entry corresponding
>+    to the desired extension.
> 
>     <p><strong>Note</strong>: If the extension does not feature a preferences
>-      panel, the Preferences button will be disabled. You can&apos;t access
>+      panel, the Options button will be hidden. You can&apos;t access
>       preferences of disabled or incompatible extensions.</p>
>   </li>
>-  <li>To disable an extension, click the entry corresponding to the desired
>-    extension, then click the Disable button. An info bar will appear to remind
>-    you that changes will apply once you restart &brandShortName;. The info bar
>-    features a Restart &brandShortName; button.</li>
>-  <li>To enable an extension, click the entry corresponding to the desired
>-    extension, then click the Enable button. An info bar will appear to remind
>-    you that changes will apply once you restart &brandShortName;. The info bar
>-    features a Restart &brandShortName; button.</li>
>-  <li>To uninstall an extension, click the entry corresponding to the
>-    desired extension, then click the Uninstall button. An info bar will
>-    appear to remind you that changes will apply once you restart
>-    &brandShortName;. The info bar features a Restart &brandShortName;
>-    button.</li>
>-  <li>To find updates for any extension in the list (including those marked as
>-    incompatible), click the Find Updates button at the bottom of the
>-    Add-ons Manager.
>-
>-    <p>If updates are found, they will be displayed in a new panel. In the
>-      panel, you can choose what extensions you want to update and then use the
>-      Install Updates button to retrieve updated Add-ons. Once downloaded, you
>-      will need to restart &brandShortName; to apply the updates.</p>
>-  </li>
>+  <li>To disable an extension, click the Disable button for the entry
>+    corresponding to the desired extension. An info bar appears if
>+    the changes will apply only once you restart &brandShortName;.
>+    Click <q>Restart Now</q> if you want to do so at this time.</li>
>+  <li>To enable an extension, click the Enable button for the entry
>+    corresponding to the desired extension. An info bar appears if
>+    the changes will apply only once you restart &brandShortName;.
>+    Click <q>Restart Now</q> if you want to do so at this time.</li>
>+  <li>To uninstall an extension, click the Remove button for the entry
>+    corresponding to the desired extension. An info bar appears if
>+    the changes will apply only once you restart &brandShortName;.
>+    Click <q>Restart Now</q> if you want to do so at this time.</li>
> </ul>


I liked the old restart text better, but then it was a button. We could say something like this, though:
"The info bar features a <q>Restart Now<q/> option." What do you think? I think it's more neutral and we get around the problem of telling someone to click a button and at the same time telling her/him to do so only if they want to do it.

> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_appearance_panel">The Appearance panel</h4>
> 
> <p>The Appearance panel in the Add-ons Manager lists the installed themes. After
>   <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
>   click the Appearance button to show the Appearance panel. There, you can
>   perform the following actions:</p>
> 
> <ul>
>-  <li>To get more information and a preview on any of the installed themes,
>-    click an entry in the list. The entry will expand and show the full
>-    description of the theme, along with a preview in the right side of the
>-    Add-ons Manager dialog (you may need to resize the dialog to properly see
>-    the preview pane).</li>
>-  <li>To use a theme, click the entry corresponding to the desired theme, then
>-    click the Use Theme button. An info bar will appear to remind you that
>-    changes will apply once you restart &brandShortName;. The info bar features
>-    a Restart &brandShortName; button.
>+  <li>To get more information about any of the installed themes, click
>+    <q>More</q> for the entry in the list. The entry will expand into the
>+    full tab and show the description of the theme along with its version
>+    information.</li>
>+  <li>To use a theme, click the Enable button for the entry corresponding
>+    to the desired theme. An info bar appears if the changes will apply only
>+    once you restart &brandShortName;. Click <q>Restart Now</q> if you want to
>+    do so at this time.

See above discussion.

>     
>-    <p><strong>Note</strong>: Contrary to extensions, you only can use one
>+    <p><strong>Note</strong>: Contrary to extensions, you can use only one
>     theme at a time.</p>
>   </li>
>-  <li>To uninstall a theme, click the entry corresponding to the desired theme,
>-    then click the Uninstall button. An info bar will appear to remind
>-    you that changes will apply once you restart &brandShortName;. The info bar
>-    features a Restart &brandShortName; button.</li>
>+  <li>To uninstall a theme, click the Remove button for the entry corresponding
>+    to the desired theme. An info bar appears if the changes will apply only
>+    once you restart &brandShortName;. Click <q>Restart Now</q> if you want to
>+    do so at this time.</li>

See above discussion.

> </ul>
> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_plugins_panel">The Plugins panel</h4>
> 
>-<p>The Plugins panel in the Add-ons Manager lists the installed Add-ons of type
>-  Plugin. After <a href="#accessing_the_add-ons_manager">accessing the Add-ons
>-  Manager</a>, click the Plugins button to show the Plugins panel. There, you
>-  can perform the following actions:</p>
>+<p>The Plugins panel in the Add-ons Manager lists the plugins found. After
>+  <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
>+  click the Plugins button to show the Plugins panel. There, you can perform
>+  the following actions:</p>
> 
> <ul>
>-  <li>To disable a plugin, click the entry corresponding to the desired plugin,
>-    then click the Disable button.</li>
>-  <li>To enable a plugin, click the entry corresponding to the desired plugin,
>-    then click the Enable button.</li>
>+  <li>To get more information about any of the plugins found, click <q>More</q>
>+    for the entry in the list. The entry will expand into the full tab and show
>+    the description of the plugin along with its version information.</li>
>+  <li>Info bars may appear for any plugins which are determined to be outdated,
>+    incompatible, or blocked for security reasons.</li>

The above <li> is just informative, so I think we should have it in a note instead. I think we can put it in the end, together with the other note.

>+  <li>Click <q>Check to see if your plugins are up to date</q> to open a new
>+    tab or window connecting to a Mozilla website to check for status and
>+    update information on all of your enabled plugins.</li>
>+  <li>To disable a plugin, click the Disable button for the entry corresponding
>+    to the desired plugin.</li>
>+  <li>To enable a plugin, click the Enable button for the entry corresponding
>+    to the desired plugin.</li>
> </ul>
> 
> <p><strong>Note</strong>: Contrary to other types of Add-ons, enabling and
>   disabling plugins doesn&apos;t require restarting &brandShortName;.</p>
> 
> <p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
> 
> <h4 id="the_languages_panel">The Languages panel</h4>
> 
>-<p>The Languages panel in the Add-ons Manager lists the installed Language
>-  Packs. This panel only appears if you have installed a Language Pack.</p>
>+<p>The Languages panel in the Add-ons Manager lists the installed language
>+  packs. This panel only appears if you have installed a language pack.</p>
> 
> <p>After <a href="#accessing_the_add-ons_manager">accessing the Add-ons
>   Manager</a>, click the Languages button to show the Languages panel. There,
>   you can perform the following actions:</p>
> 
> <ul>
>-  <li>To disable a language pack, click the entry corresponding to the desired
>-    language pack, then click the Disable button. An info bar will appear to
>-    remind you that changes will apply once you restart &brandShortName;. The
>-    info bar features a Restart &brandShortName; button.</li>
>-  <li>To enable a language pack, click the entry corresponding to the desired
>-    language pack, then click the Enable button. An info bar will appear to
>-    remind you that changes will apply once you restart &brandShortName;. The
>-    info bar features a Restart &brandShortName; button.</li>
>-  <li>To uninstall a language pack, click the entry corresponding to the
>-    desired language pack, then click the Uninstall button. An info bar will
>-    appear to remind you that changes will apply once you restart
>-    &brandShortName;. The info bar features a Restart &brandShortName;
>-    button.</li>
>+  <li>To get more information about any of the language packs, click <q>More</q>
>+    for the entry in the list. The entry will expand into the full tab and show
>+    the description of the language pack along with its update options.</li>
>+  <li>To disable a language pack, click the Disable button for the entry
>+    corresponding to the desired language pack.</li>
>+  <li>To enable a language pack, click the Enable button for the entry
>+    corresponding to the desired language pack.</li>
>+  <li>To uninstall a language pack, click the Remove button for the entry
>+    corresponding to the desired language pack.</li>
> </ul>
> 
> <p><strong>Note</strong>: Enabling a language pack in the Language panel
>   doesn&apos;t change the language shown in &brandShortName;&apos;s user
>   interface, it only makes the language available for selection in the
>   <a href="cs_nav_prefs_appearance.xhtml#appearance">Appearance Preferences
>-  panel</a>.</p>
>+  panel</a>. You have to quit and restart &brandShortName; after making
>+  any changes in the selected language pack.</p>

It's a bit of an overkill with the restart information since we actually say that both in the Appearance Preferences panel ui _and_ the Appearance Preferences panel help :-) . So I think we can remove it.

Comment 24

[rsx11m]

Attachment: Part II: panel descriptions (v4)

Ok, this should be "it" :-)

(In reply to Stefan [:stefanh] from comment #23)
> I completely agree with the hybrid version here, but I think the second and
> third <li> is bit out of context. They're not as straight-forward as the
> other ones (one is purely descriptional, the other informs you that you
> _can_ do things). I think we should put the text from those 2 into the first
> <li> (might need some minor re-write). That would also make the last 2
> <li>:s more logical. What do you think?

Agreed, I've combined those three bullet points and made the descriptional part a bit more specific which sort options exist and how to get to installed Add-ons.

> The "There, you can perform the following actions:" in the intro doesn't
> really fit with the last <li> here. Otoh, it would look odd with just one
> <li>. So, what if we removed the "There, you can perform the following
> actions:"?

That last sentence is a standard phrase found in the default introduction only anyway, thus removing it won't loose any information. So done.

> I liked the old restart text better, but then it was a button. We could say
> something like this, though:
> "The info bar features a <q>Restart Now<q/> option." What do you think? I
> think it's more neutral and we get around the problem of telling someone to
> click a button and at the same time telling her/him to do so only if they
> want to do it.

I'm ok with that, changed in all five instances relating to the panels.

> The above <li> is just informative, so I think we should have it in a note
> instead. I think we can put it in the end, together with the other note.

So done, I've made it a <ul> of two items similar to the other instances where we have multiple notes as they aren't directly related to each other.

> It's a bit of an overkill with the restart information since we actually say
> that both in the Appearance Preferences panel ui _and_ the Appearance
> Preferences panel help :-) . So I think we can remove it.

Done.

Comment 25

[Stefan [:stefanh]]

Comment on attachment 714794 [details] [diff] [review]
Part II: panel descriptions (v4)

Nice work :-) Just 2 nits:


>+  <li>To search for Add-ons based on name, description or tags, type a
>+    word or phrase into the Search box and press
>+    <span class="mac"><kbd>Return</kbd></span><span
>+    class="noMac"><kbd>Enter</kbd></span>. The search panel will open and
>+    display a list of matching Add-ons that are compatible with your current
>+    version of &brandShortName;. You can sort the results by name or date of
>+    the most recent release. You can also search your installed Add-ons by
>+    clicking on <q>My Add-ons</q>.</li>

Oops, not clicking on ;-)

>+  <li>To get additional information about a specific Add-on in the list,
>+    click <q>More</q> for that entry.</li>
>+  <li>To install an Add-on in the list, click its Install button.</li>
>+</ul>
>+
>+<p>[<a href="#using_the_add-ons_manager">Return to beginning of section</a>]</p>
>+
> <h4 id="the_get_add-ons_panel">The Get Add-ons panel</h4>
> 
> <p>The Get Add-ons panel in the Add-ons Manager uses web services provided by
>   the Mozilla Add-ons website to present a list of recommended Add-ons, as
>-  well as giving you the option to search all available Mozilla Add-ons
>-  directly from the Add-ons Manager. After
>+  well as giving you the option to browse the available Mozilla Add-ons. After
>   <a href="#accessing_the_add-ons_manager">accessing the Add-ons Manager</a>,
>-  click the Get Add-ons button to show the Get Add-ons panel. There, you can
>-  perform the following actions:</p>
>+  click the Get Add-ons button to show the Get Add-ons panel.</p>

I think we should end with a ":" here and not with a "."

Comment 26

[rsx11m]

Attachment: Part II: panel descriptions (v5), pushed (comment #29)

Nits addressed, thanks!

Comment 27

[rsx11m]

Push of attachment 714912 [details] [diff] [review] on trunk/comm-central, please.
And, his bug can be closed after that.

Comment 28

[rsx11m]

(s/his/this/)

Comment 29

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/comm-central/rev/658e70ff9e54