336389 - document the new "Add-ons" UI (formerly Extensions and Themes)

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Steffen Wilberg]

Comment 1

[Steffen Wilberg]

Attachment: v1

Since the UI is consolidated, I've done that to the docs as well. I've also documented "Enable", "Disable", "Preferences", and "Visit Home Page" for the first time.

Comment 2

[Steffen Wilberg]

Attachment: unbitrotted

Comment 3

[Steffen Wilberg]

Attachment: unbitrotted

Also replaced Firefox by &brandShortName;.

Comment 4

[u60234]

Comment on attachment 224259 [details] [diff] [review]
unbitrotted

>Index: mozilla/browser/locales/en-US/chrome/help/customization.xhtml
>===================================================================

>+<h3 id="add_ons_uninstalling">Disabling, Enabling, Uninstalling Add-ons</h3>

Shouldn't there be a "and" here? Same thing in firebird-toc.rdf.

>+<p>Instead of uninstalling an extension, you can disable it so it is easily
>+  available, should you want to use it again in the future. To disable or enable
>+  an extension, select the extension of you choice, and click its
>+  <em>Disable</em> or <em>Enable</em> button.</p>

"select the extension of your choice..."?

Comment 5

[Steffen Wilberg]

> >Index: mozilla/browser/locales/en-US/chrome/help/customization.xhtml
> >===================================================================
> >+<h3 id="add_ons_uninstalling">Disabling, Enabling, Uninstalling Add-ons</h3>
> Shouldn't there be a "and" here? Same thing in firebird-toc.rdf.
Yeah, although the toc entry would get pretty long. Maybe we should just add it to the document, but not the toc.
 
> >+<p>Instead of uninstalling an extension, you can disable it so it is easily
> >+  available, should you want to use it again in the future. To disable or enable
> >+  an extension, select the extension of you choice, and click its
> >+  <em>Disable</em> or <em>Enable</em> button.</p>
> "select the extension of your choice..."?
Sure, thanks for catching that as well.

Comment 6

[u60234]

Comment on attachment 224259 [details] [diff] [review]
unbitrotted

>Index: mozilla/browser/locales/en-US/chrome/help/customization.xhtml
>===================================================================

>+<h3 id="add_ons_configuring_extensions">Configuring Extensions</h3>
>+
>+<p>Extensions often provide a dialog to configure their functionality. To open
>+  the preferences dialog of an extension, select <span class="menuPath">Tools
>+  &gt; Add-ons</span> to open the Add-ons manager, select the Extensions panel,
>+  select the extension of your choice, and click its <em>Preferences</em>
>+  button, or simply double-click the extension.</p>

Oh, and that button is called "Options" on Windows.

Comment 7

[Steffen Wilberg]

Attachment: fixed the typos and other mistakes

All right, here's a new patch, with "Disabling, Enabling, *and* Uninstalling Add-ons" in the doc but not the toc, "select the extension of you*r* choice", and "pref.pluralCaps" instead of "Preferences".

Comment 8

[Jeff Walden (gone starting June 8)]

Comment on attachment 228718 [details] [diff] [review]
fixed the typos and other mistakes

>Index: mozilla/browser/locales/en-US/chrome/help/customization.xhtml

> <p>Extensions are small add-ons to &brandShortName; that change existing
>+  browser functionality or add new functionality. Themes change the look and
>+  feel of &brandShortName;. Themes are not allowed to modify the
>+  actions or functionality of &brandShortName;, only the look. Extensions and
>+  themes are both referred to as <q>add-ons</q>.</p>

As painful as this may be to change (this could extend past this section into a lot of the patch), I think we're approaching this the wrong way here.  We've titled the section "Add-ons", but then we start off the section by talking about extensions, then themes, and then finally add-ons (ignoring the "small add-ons" part in the first sentence, which is easy to overlook).  We don't even get to extension/theme-specific info for another couple paragraphs!  The opening paragraphs should go something more like this (not that I think that this is necessarily what we want -- for one, at least, it's slightly overloaded info-wise):

Add-ons are small pieces of software which change or add to the appearance or functionality of &brandShortName;.  [start with definition]  They can do anything from adding a new button to your toolbars to changing how &brandShortName; looks to changing almost any existing &brandShortName; functionality.  [what they do]  Add-ons are managed in the Add-ons manager. Select <span class="menuPath">Tools &gt; Add-ons</span> to open it.

"Add-ons" is the new term for this stuff, and I think with what we have here we're currently doing it the disservice of trying to frame it purely in terms of the old terms.


>+<p>You can download and install many add-ons from <a href=
>+  "https://addons.mozilla.org/firefox/" target="_blank">&brandShortName;
>+  Add-ons</a>. Internet searches will find many other add-ons as well.</p>

The link here -- that doesn't work for someone rebranding Firefox.  Perhaps make it an entity instead?  I don't remember what we usually (if there is a usually) do here.


>+<p>Whenever you would like to check for a newer version of an add-on that you
>+  have installed, select <span class="menuPath">Tools &gt; Add-ons</span> to
>+  open the Add-ons manager and click the <em>Find Updates</em> button.
>+  If updates are available, the Add-ons manager displays an <em>Installation</em>
>+  panel, where you can choose the updates you want to install.

This is misleading -- the update check only occurs for the add-ons in the current pane.  I can imagine this either being fixed here or being fixed by adding this paragraph (with reductions and changes) to each of the add-on type sections.


> You can check for updates
>+  manually by clicking the <em>Find Updates</em> button.</p>

Isn't this redundant with the previous paragraph?


>+<h3 id="add_ons_uninstalling">Disabling, Enabling, and Uninstalling Add-ons</h3>
>+
>+<p>Should you wish to remove an add-on from &brandShortName;, select <span
>+  class="menuPath">Tools &gt; Add-ons</span> to open the Add-ons manager,
>+  select the add-on you wish to remove, and click its <em>Uninstall</em> button.
>+</p>

We should try to minimize the number of places where we describe opening the Add-ons manager -- perhaps a small section in this document dedicated to describing how to open it and very briefly explaining what functionality it provides is worthwhile.  We could then link back to it as necessary without cluttering the document with redundancies.


>+<p>Instead of uninstalling an extension, you can disable it so it is easily
>+  available, should you want to use it again in the future. To disable or enable
>+  an extension, select the extension of your choice, and click its
>+  <em>Disable</em> or <em>Enable</em> button.</p>

I suspect this information needs to go elsewhere, but I'm not certain enough of structure yet to say where.


>+<h3 id="add_ons_home_page">Visit the home page of an Add-on</h3>
>+
>+<p>The home page of an add-on might provide news, documentation and support for
>+  the add-on. To visit the home page of an add-on, select <span class=
>+  "menuPath">Tools &gt; Add-ons</span> to open the Add-ons manager,
>+  select the add-on of your choice, <span class="mac">press &ctrlKey; and click
>+  on</span><span class="noMac">right-click</span> the add-on and select
>+  <em>Visit Home Page</em> from the context menu.</p>

Ugh.  As a general rule, I don't think we should refer to add-on functionality not in visible UI when an add-on is selected.  A short note such as, "further functionality such as...is available by <right-click action>" is probably as much as we should do.


>+<h3 id="add_ons_configuring_extensions">Configuring Extensions</h3>
>+
>+<p>Extensions often provide a dialog to configure their functionality. To open
>+  the preferences dialog of an extension, select <span class="menuPath">Tools
>+  &gt; Add-ons</span> to open the Add-ons manager, select the Extensions panel,
>+  select the extension of your choice, and click its <em>&pref.pluralCaps;</em>
>+  button, or simply double-click the extension.</p>


>+<h3 id="add_ons_switching_themes">Switching Themes</h3>

I didn't realize until here that we didn't have specific sections for extensions and themes.  Instead, we have a bunch of paragraphs and headers for generalized add-on stuff followed by (at the same heading level) extension and theme stuff.  At the very least, I think we need to put the type-specific info into a lower heading level than the general stuff -- maybe somehow insert a definition list with extensions,themes as the titles and the appropriate info as the definitions?  However we do it, I'd like to avoid having full-blown sections for themes and extensions given how similar they appear now, if possible.


>Index: mozilla/browser/locales/en-US/chrome/help/menu_reference.xhtml

>+  <p>Opens the Add-ons manager, where you can see, install, configure, update,

I'm not entirely certain why, but I think "view" is more appropriate here than "see".


I think there's still a lot to clear up here, so I didn't bother reviewing the RDF changes.

(By the way, I'm spending the rest of the day reviewing the backlog of patches on which you've requested review from me, and if I don't finish with that backlog today it's first thing on my agenda tomorrow.  :-) )

Comment 9

[Steffen Wilberg]

Attachment: patch v2

(In reply to comment #8)
> >Index: mozilla/browser/locales/en-US/chrome/help/customization.xhtml
> Add-ons are small pieces of software which change or add to the appearance or
> functionality of &brandShortName;.  [start with definition]  They can do
> anything from adding a new button to your toolbars to changing how
> &brandShortName; looks to changing almost any existing &brandShortName;
> functionality.  [what they do]  Add-ons are managed in the Add-ons manager.
> Select <span class="menuPath">Tools &gt; Add-ons</span> to open it.
> 
> "Add-ons" is the new term for this stuff, and I think with what we have here
> we're currently doing it the disservice of trying to frame it purely in terms
> of the old terms.
I agree that we need to make "Add-ons" more prominent. But we can't drop the distinction between extensions and themes since they have separate UI in the add-ons manager and differ in functionality. So I'm starting with describing add-ons in general this time before reaching down to extensions and themes. 
I've also added better definitions of extensions and themes.

> >+<p>You can download and install many add-ons from <a href=
> >+  "https://addons.mozilla.org/firefox/" target="_blank">&brandShortName;
> >+  Add-ons</a>. Internet searches will find many other add-ons as well.</p>
> 
> The link here -- that doesn't work for someone rebranding Firefox.  Perhaps
> make it an entity instead?  I don't remember what we usually (if there is a
> usually) do here.
We have a couple of other links to mozilla.org pages. Rebranding Firefox requires a bunch of code changes anyway (remember the Deer Park/Bon Echo/Minefiled patches), so they can change the docs as well if they really have to.

> >+<p>Whenever you would like to check for a newer version of an add-on that you
> >+  have installed, select <span class="menuPath">Tools &gt; Add-ons</span> to
> >+  open the Add-ons manager and click the <em>Find Updates</em> button.
> >+  If updates are available, the Add-ons manager displays an <em>Installation</em>
> >+  panel, where you can choose the updates you want to install.
> 
> This is misleading -- the update check only occurs for the add-ons in the
> current pane.  I can imagine this either being fixed here or being fixed by
> adding this paragraph (with reductions and changes) to each of the add-on type
> sections.
Fixed. And I'm starting with describing the automatic check since the update notification has been made much more prominent, so the manual update check has lost most of its importance. 

> We should try to minimize the number of places where we describe opening the
> Add-ons manager -- perhaps a small section in this document dedicated to
> describing how to open it and very briefly explaining what functionality it
> provides is worthwhile.  We could then link back to it as necessary without
> cluttering the document with redundancies.
Done. I've created a section "Using the Add-ons manager".

> >+<p>Instead of uninstalling an extension, you can disable it so it is easily
> >+  available, should you want to use it again in the future. To disable or enable
> >+  an extension, select the extension of your choice, and click its
> >+  <em>Disable</em> or <em>Enable</em> button.</p>
> 
> I suspect this information needs to go elsewhere, but I'm not certain enough of
> structure yet to say where.
Hmm?

> >+<h3 id="add_ons_home_page">Visit the home page of an Add-on</h3>
> >+
> >+<p>The home page of an add-on might provide news, documentation and support for
> >+  the add-on. To visit the home page of an add-on, select <span class=
> >+  "menuPath">Tools &gt; Add-ons</span> to open the Add-ons manager,
> >+  select the add-on of your choice, <span class="mac">press &ctrlKey; and click
> >+  on</span><span class="noMac">right-click</span> the add-on and select
> >+  <em>Visit Home Page</em> from the context menu.</p>
> 
> Ugh.  As a general rule, I don't think we should refer to add-on functionality
> not in visible UI when an add-on is selected.  A short note such as, "further
> functionality such as...is available by <right-click action>" is probably as
> much as we should do.
Done ("Further functionality").

> I didn't realize until here that we didn't have specific sections for
> extensions and themes.  Instead, we have a bunch of paragraphs and headers for
> generalized add-on stuff followed by (at the same heading level) extension and
> theme stuff.  At the very least, I think we need to put the type-specific info
> into a lower heading level than the general stuff -- maybe somehow insert a
> definition list with extensions,themes as the titles and the appropriate info
> as the definitions?  However we do it, I'd like to avoid having full-blown
> sections for themes and extensions given how similar they appear now, if
> possible.
Done. I've added a section "Tasks specific to extensions or themes".

 
> >Index: mozilla/browser/locales/en-US/chrome/help/menu_reference.xhtml
> 
> >+  <p>Opens the Add-ons manager, where you can see, install, configure, update,
> 
> I'm not entirely certain why, but I think "view" is more appropriate here than
> "see".
Sure.

> (By the way, I'm spending the rest of the day reviewing the backlog of patches
> on which you've requested review from me, and if I don't finish with that
> backlog today it's first thing on my agenda tomorrow.  :-) )
Sounds to good to be true...

Comment 10

[Steffen Wilberg]

So the new structure is:

Add-ons (extensions and themes)
  Getting and Installing Add-ons
  Using the Add-ons manager
    Updating Add-ons
    Disabling, Enabling, and Uninstalling Add-ons
    Further functionality
  Tasks specific to extensions or themes
    Configuring Extensions
    Switching Themes

The "Tasks specific to extensions or themes" section should also belong to "Using the Add-ons manager", but it's already down at <h3>, with its two subitems at <h4>...

Comment 11

[Steffen Wilberg]

Attachment: patch v2.1

I've made "Using the Add-ons manager" a h2 so I can go down to h3 and h4:

Add-ons (extensions and themes)
  Getting and Installing Add-ons
  Using the Add-ons manager
    Updating Add-ons
    Disabling, Enabling, and Uninstalling Add-ons
    Further functionality
    Tasks specific to extensions or themes
      Configuring Extensions
      Switching Themes

Comment 12

[Jeff Walden (gone starting June 8)]

Comment on attachment 229322 [details] [diff] [review]
patch v2.1

I long for a flag that means, "this looks good, but let me double-check the changes you make to this before checkin".  :-\


> Sounds to good to be true...

And if it sounds too good to be true, ...  :-(  I think I have enough time now to get through reviews, so there's a better chance that this will happen now than before.


> I agree that we need to make "Add-ons" more prominent. But we can't drop the
> distinction between extensions and themes since they have separate UI in the
> add-ons manager and differ in functionality. So I'm starting with describing
> add-ons in general this time before reaching down to extensions and themes. 
> I've also added better definitions of extensions and themes.

Exactly what I wanted.  :-)


>Index: mozilla/browser/locales/en-US/chrome/help/customization.xhtml
>+   <li><a href="#add_ons">Add-ons (extensions and themes)</a></li>

I don't like this, but I suppose it's at the least rationalizable as a searchability win (until users get used to "add-ons" as opposed to e/t).


>+  <dd>Themes are skins for &brandShortName;. They allow you to change the look
>+    and feel of the user interface and personalize it to your tastes. A theme
>+    can simply change colors, or it can change every piece of its appearance.</dd>

For the first sentence, how about "Themes modify &brandShortName;'s appearance." (maybe with "but not its functionality"?)?  "Themes are skins" just doesn't sound right.

Also, s/the user interface/&brandShortName;/, s/colors/button images/, and s/its/&brandShortName;'s/


>+<h2 id="add_ons_manager">Using the Add-ons manager</h2>

This (and probably all further levels) are off by one.  ;-)


>+<p>Add-ons are managed in the Add-ons manager. Select <span class=

Nit: I prefer not breaking within an attribute, so move the "class=" to the next line.  I think this happens other place(s?) here too -- search for = followed by whitespace or newline should get it/them.


>+<p>By default, &brandShortName; will periodically check when a new version for
>+  one of your installed add-ons is available, and prompt you at the next start
>+  to install any updates.

s/and prompt/and if any are available, it will prompt/


>+<h3 id="add_ons_uninstalling">Disabling, Enabling, and Uninstalling Add-ons</h3>
>+
>+<p>Should you wish to remove an add-on from &brandShortName;, select the add-on
>+  you wish to remove, and click its <em>Uninstall</em> button.
>+</p>
>+
>+<p>Instead of uninstalling an extension, you can disable it so it is easily
>+  available, should you want to use it again in the future. To disable or enable
>+  an extension, select the extension of your choice, and click its
>+  <em>Disable</em> or <em>Enable</em> button.</p>
>+  
>+<p>You need to restart &brandShortName; for changes to take effect.</p>

I feel we want to encourage the non-destructive action of disabling an extension over uninstalling it.  Can you flip these two paragraphs and tweak as necessary to make sense?  (I *think* that's what I meant in my last comment -- not 100% sure, but more certain than not.)


>+<p>Further functionality such as <em>Visit Home Page</em> and <em>About</em> is
>+  available by selecting the add-on of your choice, <span class="mac">press
>+  &ctrlKey; and click on</span><span class="noMac">right-click</span> the add-on
>+  and select the respective item from the context menu.</p>

"pressing", "right-clicking", "selecting"

Comment 13

[Steffen Wilberg]

Attachment: patch v2.5

(In reply to comment #12)
> And if it sounds too good to be true, ...  :-(  I think I have enough time now
> to get through reviews, so there's a better chance that this will happen now
> than before.
Great!! I was kind of expecting that since the dust settled a bit around the prefwindow.

> >+  <dd>Themes are skins for &brandShortName;. They allow you to change the look
> >+    and feel of the user interface and personalize it to your tastes. A theme
> >+    can simply change colors, or it can change every piece of its appearance.</dd>
> 
> For the first sentence, how about "Themes modify &brandShortName;'s
> appearance." (maybe with "but not its functionality"?)?  "Themes are skins"
> just doesn't sound right.
Fixed.

> Also, s/the user interface/&brandShortName;/, s/colors/button images/, and
> s/its/&brandShortName;'s/
Fixed. Altough "&brandShortName;'s appearance" is now repeated in that paragraph.

> >+<h2 id="add_ons_manager">Using the Add-ons manager</h2>
> 
> This (and probably all further levels) are off by one.  ;-)
That's intentional, see comment 11 :-)

> >+<p>Add-ons are managed in the Add-ons manager. Select <span class=
> 
> Nit: I prefer not breaking within an attribute, so move the "class=" to the
> next line.  I think this happens other place(s?) here too -- search for =
> followed by whitespace or newline should get it/them.
Fixed, and two href= as well.

> >+<p>By default, &brandShortName; will periodically check when a new version for
> >+  one of your installed add-ons is available, and prompt you at the next start
> >+  to install any updates.
> 
> s/and prompt/and if any are available, it will prompt/
Fixed, but with s/and if/. If/

> I feel we want to encourage the non-destructive action of disabling an
> extension over uninstalling it.  Can you flip these two paragraphs and tweak as
> necessary to make sense?  (I *think* that's what I meant in my last comment --
> not 100% sure, but more certain than not.)
Fixed.

> >+<p>Further functionality such as <em>Visit Home Page</em> and <em>About</em> is
> >+  available by selecting the add-on of your choice, <span class="mac">press
> >+  &ctrlKey; and click on</span><span class="noMac">right-click</span> the add-on
> >+  and select the respective item from the context menu.</p>
> 
> "pressing", "right-clicking", "selecting"
Fixed.

I haven't yet updated the add-ons url to this one:
http://%locale%.add-ons.mozilla.com/%LOCALE%/%APP%/%VERSION%/extensions/
Does help content have chrome privs to access the url formatter?

Comment 14

[Steffen Wilberg]

Actually, comment 11 is wrong, the structure is like this:
Add-ons (extensions and themes)
  Getting and Installing Add-ons
Using the Add-ons manager
  Updating Add-ons
  Disabling, Enabling, and Uninstalling Add-ons
  Further functionality
  Tasks specific to extensions or themes
    Configuring Extensions
    Switching Themes

Also see comment 10.

Comment 15

[Jeff Walden (gone starting June 8)]

Comment on attachment 235312 [details] [diff] [review]
patch v2.5

(In reply to comment #13)
> > Also, s/the user interface/&brandShortName;/, s/colors/button images/, and
> > s/its/&brandShortName;'s/
> Fixed. Altough "&brandShortName;'s appearance" is now repeated in that
> paragraph.

Yeah; I can't think of another way to do it.  If you come up with something else, great, but this will work for now.


> > This (and probably all further levels) are off by one.  ;-)
> That's intentional, see comment 11 :-)

s/11/14/  ;-)


> > I feel we want to encourage the non-destructive action of disabling an
> > extension over uninstalling it.  Can you flip these two paragraphs and tweak as
> > necessary to make sense?  (I *think* that's what I meant in my last comment --
> > not 100% sure, but more certain than not.)
> Fixed.

See comments below.


> I haven't yet updated the add-ons url to this one:
> http://%locale%.add-ons.mozilla.com/%LOCALE%/%APP%/%VERSION%/extensions/
> Does help content have chrome privs to access the url formatter?

We can hand-code JS to do that somewhat (given that some of those things are available on the navigator object), but I don't think we can get all of it.  Followup bug to decide what to do?


>+<h3 id="add_ons_uninstalling">Disabling, Enabling, and Uninstalling Add-ons</h3>
>+
>+<p>Extensions tend to clutter up &brandShortName;'s menus and toolbars,
>+  especially if you've got a lot of them installed, and some of them might even
>+  slow down &brandShortName; or cause it to run instable. If you want to get rid
>+  of an extension, you can either disable it temporarily, so it is easily
>+  available should you want to enable it again in the future, or uninstall it.

I don't think we should presume to guess why an extension is being uninstalled or suggest why one might want to disable or uninstall one.  How about removing the first sentence and parenthesize "so it is easliy available...in the future"?


>+  Themes can only be uninstalled.</p>

Add in ", but switching to the default theme will effectively disable any theme."?  Help me on this, because I think we need to recognize this but ideally not with this string (it's a bit goofy).


>+<p>To disable or enable an extension, select the extension of your choice, and
>+  click its <em>Disable</em> or <em>Enable</em> button.</p>
>+
>+<p>Should you wish to remove an add-on from &brandShortName;, select the add-on
>+  you wish to remove, and click its <em>Uninstall</em> button.</p>

Combine these into one paragraph, remove the commas after the "select" clauses, and s/Should you wish t/T/


>+<p>You need to restart &brandShortName; for changes to take effect.</p>

I don't think this needs to be in the previous paragraph, but your call.  :-)

Comment 16

[Steffen Wilberg]

Fixed on trunk.

> >+<p>Extensions tend to clutter up &brandShortName;'s menus and toolbars,
> >+  especially if you've got a lot of them installed, and some of them might even
> >+  slow down &brandShortName; or cause it to run instable. If you want to get rid
> >+  of an extension, you can either disable it temporarily, so it is easily
> >+  available should you want to enable it again in the future, or uninstall it.
> 
> I don't think we should presume to guess why an extension is being uninstalled
> or suggest why one might want to disable or uninstall one.  How about removing
> the first sentence and parenthesize "so it is easliy available...in the
> future"?
I removed the first sentence, but kept the commas:
  "If you want to get rid of an extension, you can either disable it temporarily,
  so it is easily available should you want to enable it again in the future,
  or uninstall it."

> >+  Themes can only be uninstalled.</p>
> 
> Add in ", but switching to the default theme will effectively disable any
> theme."?  Help me on this, because I think we need to recognize this but
> ideally not with this string (it's a bit goofy).
Themes can only be uninstalled since all themes except the current one are disabled automatically.


> >+<p>To disable or enable an extension, select the extension of your choice, and
> >+  click its <em>Disable</em> or <em>Enable</em> button.</p>
> >+
> >+<p>Should you wish to remove an add-on from &brandShortName;, select the add-on
> >+  you wish to remove, and click its <em>Uninstall</em> button.</p>
> 
> Combine these into one paragraph, remove the commas after the "select" clauses,
> and s/Should you wish t/T/
Fixed.


> >+<p>You need to restart &brandShortName; for changes to take effect.</p>
> 
> I don't think this needs to be in the previous paragraph, but your call.  :-)
Agreed.

Comment 17

[Mike Schroepfer]

Comment on attachment 235312 [details] [diff] [review]
patch v2.5

a=schrep/beltnzer for drivers.

Comment 18

[Steffen Wilberg]

Fixed on branch!

Comment 19

[Steffen Wilberg]

*** Bug 353101 has been marked as a duplicate of this bug. ***