416234 - Add Clear Private Data (preferences and menu) documentation to Help

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[Robert Kaiser]

When bug 416233 introduces a sanitize option to SeaMonkey, help should be updated to reflect that.

Comment 1

[Lars P M]

A link to the preferences help section for "Private Data" (Privacy & Security main preferences pane) is missing from this page: <http://mxr.mozilla.org/seamonkey/source/suite/locales/en-US/chrome/common/help/privsec_help.xhtml>

The general description of the sanitize features should probably end up somewhere in relation to (just before?) the section about encrypting sensitive information: <http://mxr.mozilla.org/seamonkey/source/suite/locales/en-US/chrome/common/help/using_priv_help.xhtml#1361>

Comment 4

[rsx11m]

Since I've just worked on the preference panel for this function (bug 835134), I'll try to get the documentation done (along with bug 631566 and bug 771534) within the SM 2.19 timeframe.

Comment 5

[rsx11m]

(In reply to Lars P M from comment #1)
> A link to the preferences help section for "Private Data" (Privacy &
> Security main preferences pane) is missing from this page:

Yes, and since Private Data has now its own pane under Privacy & Security, the description of that pane should be handled here as well. This would avoid splitting up related menu and preference parts. Also, bug 631566 will only have to deal with the User Tracking and Safe Browsing preferences of the main pane.

> The general description of the sanitize features should probably end up
> somewhere in relation to (just before?) the section about encrypting
> sensitive information:

This looks like a good spot, in the flow coming from Cookies and Passwords to Private Data. It wouldn't be in the same order as the Privacy & Security panes, but given that not all panes are described in using_priv_help.xhtml anyway, that shouldn't be a problem.

Note that I won't touch the Cookie Manager and Password Manager sections, well knowing that they have been partially obsoleted by introduction of the Data Manager, but that's the task of bug 599097.

Comment 6

[rsx11m]

Attachment: Proposed patch

This patch introduces a new "Clearing Private Data" section with 3 subsections:

1. "Types of Private Data" explains what this is all about and then gives a
   brief explanation for each type (= each checkbox in the panes).

 - I had this a bullet list first but then saw the cookie table in an earlier
   section, where I'd think that due to the large number of items, the table
   looks much better than a list. Thus, I'm going with it.
 - Each item has a "catch phrase" highlighted by <em> in the explanation.
 - Links go directly to the respective preference panes. For Offline Apps, add
   bug 771534 attachment 711809 [details] [diff] [review] to test this properly.

2. "Security & Privacy - Private Data" is the usual description of the UI
    elements in that pane with the actual labels highlighted in <strong>.

 - I've put "Clear Now" at the very end, otherwise the flow isn't good.
 - Rather than listing all the checkbox labels again, there is a generic
   explanation along with a link to the "Types of Private Data" section.

3. "Clear Private Data Now" documents the "Tools" menu item equivalent to the
   "Clear Now" button.

 - This is a bit more detailed than the "Clear Now" button as it needs
   additional references back to the Private Data pane description.
 - Again, there is a generic explanation along with a link to the
   "Types of Private Data" section.

(Quoting rsx11m from bug 631566 comment #6)
> Bug 835134 attachment 709466 [details] [diff] [review] adds a help topic for
> the new Private Data pane that needs to be wired, helpTopic="privatedata_prefs".

This has been taken care of in this patch as well, along with a new link to section (2) from privsec_help.xhtml.

Comment 7

[rsx11m]

Attachment: Proposed patch (v2)

(Quoting from comment #6)
> 1. "Types of Private Data" explains what this is all about and then gives a
>    brief explanation for each type (= each checkbox in the panes).

After another close look on the History preference pane, I've noticed that in the initial patch, I'm referring to some UI features which don't (no longer, or never did) exist. I've removed those and made a couple of other improvements.

No changes to the other sections.

Comment 8

[Ian Neal]

Comment on attachment 712007 [details] [diff] [review]
Proposed patch (v2)

>+++ b/suite/locales/en-US/chrome/common/help/using_priv_help.xhtml

>+  may be gathered and stored by &brandShortName;. This section describes the
>+  types of such private data and options to remove them automatically when
>+  shutting down &brandShortName; or when requested manually.</p>
Sounds a bit awkward perhaps:
"This section describes the
types of such private data and options to remove them either manually by
request or automatically when shutting down &brandShortName;."

>+      <td>Cache</td>
>+      <td>The cache is a <em>short-term memory</em> for web pages and other
>+        data (like e-mail attachments or remote images in messages) to avoid
>+        that these items have to be requested again from the server for pages
Perhaps:
"The cache is a <em>short-term store</em> for web pages and other
data (like e-mail attachments or remote images in messages) to avoid
having these items being requested again from the server for pages..."
I'm not sure that e-mail attachments are cached either, might be worth checking with #maildev

>+      <td>Cookies</td>
>+      <td>Cookies are <em>small pieces of information</em> that websites use to
>+        keep track of users and sessions, or to store website preferences. Use
>+        the <a href="using_priv_help.xhtml#cookies">Cookies preferences</a> to
>+        specify to which extent cookies are permitted and for how long they are
>+        kept.</td>
"what extent" rather than "which extent" here.

>+      <td>Authenticated Sessions</td>
>+      <td>Websites may require <em>authentication</em> (user name and password,
"user name" is correct here but I've spotted we have used "username" in http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/help/passwords_help.xhtml#422 and http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/help/mailnews_organizing.xhtml#796
That is out of scope of this bug.

>+        with this mechanism in form of a pop-up dialog) and can keep track of
"this mechanism" is wrong, perhaps "this application" or "&brandShortName;".
"in the form of..." instead of "in form of..."

>+        such by authenticated sessions. Clearing those may prompt the site to
>+        ask you for your credentials again when you proceed to the next page
>+        after this information is cleared.</td>
You're clearing it twice in this sentence.

>+<p>This section describes how to use the Private Data preferences panel to
>+  determine when and which type of private data shall be deleted. If
"should" instead of "shall" here perhaps?

>+  <li><strong>Ask me before clearing private data</strong>: Check this option
>+    to reconfirm clearing of the selected private data, also allowing to change
>+    the selection, rather than clearing them without any interaction.</li>
Perhaps:
"Check this option for &brandShortName; to prompt you before clearing the selected private data, also allowing you to change the selection, rather than clearing them without any interaction."

>+  <li><strong>Clear Now</strong>: Click this button to initiate clearing of
>+    private data immediately, depending on the preferences selected in
>+    this panel:
>+    <ul>
>+      <li>When the <q>Ask me before clearing private data</q> option is checked,
>+        &brandShortName; opens a dialog window where you can confirm and change
>+        the items to be cleared.</li>
>+      <li>When <q>Ask me before clearing private data</q> is <em>not</em>
>+        checked, all types selected to be cleared by default will be deleted
>+        without any further dialog.</li>
Perhaps "prompts" instead of "dialog"
I'm just wondering if these last two items should be moved to the "Note" section further down.

>+  <li>When <q>Ask me before clearing private data</q> is <em>not</em> checked,
>+    all types selected in the <a href="#private_data_prefs">Private Data
>+    preferences</a> to be cleared by default will be deleted without any
>+    further dialog.</li>
Perhaps "prompts" instead of "dialog"

Let me know your views.
f+ but want to review the new patch.

Comment 9

[rsx11m]

(In reply to Ian Neal from comment #8)
> >+      <td>Cache</td>
> >+      <td>The cache is a <em>short-term memory</em> for web pages and other
> >+        data (like e-mail attachments or remote images in messages) to avoid
> >+        that these items have to be requested again from the server for pages
> Perhaps:
> "The cache is a <em>short-term store</em> for web pages and other
> data (like e-mail attachments or remote images in messages) to avoid
> having these items being requested again from the server for pages..."

Sounds fine.

> I'm not sure that e-mail attachments are cached either, might be worth
> checking with #maildev

Since bug 439731 they are cached in the disk cache, as long as synchronization isn't used for that account (has to be IMAP, obviously), and the setting of the *.mime_parts_on_demand preferences should only decide if the attachment is stored separately or along with the message.

> >+      <td>Websites may require <em>authentication</em> (user name and password,
> "user name" is correct here but I've spotted we have used "username" in
> http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/
> help/passwords_help.xhtml#422 and
> http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/
> help/mailnews_organizing.xhtml#796
> That is out of scope of this bug.

Coincidentally I just had a similar discussion with Neil in bug 835134 comment #37 on the question "web site" (correct by Merriam Webster, which I usually use as reference) or "website" which is more commonly used. I think that "user name" vs. "username" falls into the same category. Re "website" I found following rationale:

http://www.thefreedictionary.com/Website "Usage Note: The transition from World Wide Web site to Web site to website as a single uncapitalized word mirrors the development of other technological expressions which have tended to take unhyphenated forms as they become more familiar. Thus email is gaining ground over the forms E-mail and e-mail, especially in texts that are more technologically oriented. Similarly, there is an increasing preference for closed forms like homepage, online, and printout."

Thus, I think we should go with "username" especially given that it's consistently used elsewhere already.

> >+  <li><strong>Clear Now</strong>: Click this button to initiate clearing of
> >+    private data immediately, depending on the preferences selected in
> >+    this panel:
> >+    <ul>
> >+      <li>When the <q>Ask me before clearing private data</q> option is checked,
> >+        &brandShortName; opens a dialog window where you can confirm and change
> >+        the items to be cleared.</li>
> >+      <li>When <q>Ask me before clearing private data</q> is <em>not</em>
> >+        checked, all types selected to be cleared by default will be deleted
> >+        without any further dialog.</li>
> Perhaps "prompts" instead of "dialog"

It's more a dialog (where you can check boxes) rather than a prompt (which usually has limited choices only line "Ok" or "Cancel" maybe with a single box to not show it again; this is more complex, though modified options won't persist).

> I'm just wondering if these last two items should be moved to the "Note"
> section further down.

I was struggling with this myself and initially only had a forward reference to the "Clear Private Data Now" prompt. It is part of the workflow associated with the "Clear Now" button, thus I kept it in this context and provided a shorter version explaining what the user should expect when clicking on it.

I agree with all of your other suggestions.

Comment 10

[Ian Neal]

(In reply to rsx11m from comment #9)
> (In reply to Ian Neal from comment #8)
> > I'm not sure that e-mail attachments are cached either, might be worth
> > checking with #maildev
> 
> Since bug 439731 they are cached in the disk cache, as long as
> synchronization isn't used for that account (has to be IMAP, obviously), and
> the setting of the *.mime_parts_on_demand preferences should only decide if
> the attachment is stored separately or along with the message.
I use IMAP and I've never really noticed it, but it is across a LAN so probably hard to notice anyway. If it only works for IMAP and not for POP then might be worth making that distinction.

> > >+      <td>Websites may require <em>authentication</em> (user name and password,
> > "user name" is correct here but I've spotted we have used "username" in
> > http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/
> > help/passwords_help.xhtml#422 and
> > http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/
> > help/mailnews_organizing.xhtml#796
> > That is out of scope of this bug.
> 
> Coincidentally I just had a similar discussion with Neil in bug 835134
> comment #37 on the question "web site" (correct by Merriam Webster, which I
> usually use as reference) or "website" which is more commonly used. I think
> that "user name" vs. "username" falls into the same category. Re "website" I
> found following rationale:
> 
> http://www.thefreedictionary.com/Website "Usage Note: The transition from
> World Wide Web site to Web site to website as a single uncapitalized word
> mirrors the development of other technological expressions which have tended
> to take unhyphenated forms as they become more familiar. Thus email is
> gaining ground over the forms E-mail and e-mail, especially in texts that
> are more technologically oriented. Similarly, there is an increasing
> preference for closed forms like homepage, online, and printout."
It is more to do with British English vs American English. British tend to use web site, American website.
> 
> Thus, I think we should go with "username" especially given that it's
> consistently used elsewhere already.
> 
> > >+  <li><strong>Clear Now</strong>: Click this button to initiate clearing of
> > >+    private data immediately, depending on the preferences selected in
> > >+    this panel:
> > >+    <ul>
> > >+      <li>When the <q>Ask me before clearing private data</q> option is checked,
> > >+        &brandShortName; opens a dialog window where you can confirm and change
> > >+        the items to be cleared.</li>
> > >+      <li>When <q>Ask me before clearing private data</q> is <em>not</em>
> > >+        checked, all types selected to be cleared by default will be deleted
> > >+        without any further dialog.</li>
> > Perhaps "prompts" instead of "dialog"
> 
> It's more a dialog (where you can check boxes) rather than a prompt (which
> usually has limited choices only line "Ok" or "Cancel" maybe with a single
> box to not show it again; this is more complex, though modified options
> won't persist).
I was using "prompts" as being "prompted for information" rather than "prompt boxes". If we do not use "prompts" then it should be "dialog boxes" with the word "any" otherwise change it to "a dialog box".
> 
> > I'm just wondering if these last two items should be moved to the "Note"
> > section further down.
> 
> I was struggling with this myself and initially only had a forward reference
> to the "Clear Private Data Now" prompt. It is part of the workflow
> associated with the "Clear Now" button, thus I kept it in this context and
> provided a shorter version explaining what the user should expect when
> clicking on it.
Okay, agreed.
> 
> I agree with all of your other suggestions.
Thanks :)

Comment 11

[rsx11m]

Attachment: Proposed patch (v3)

All items addressed.

(In reply to Ian Neal from comment #8)
> >+        with this mechanism in form of a pop-up dialog) and can keep track of
> "this mechanism" is wrong, perhaps "this application" or "&brandShortName;".
> "in the form of..." instead of "in form of..."

I got rid of this entirely and simply stated that the user is prompted for it by a pop-up dialog.

> "Check this option for &brandShortName; to prompt you before clearing the
> selected private data, also allowing you to change the selection, rather
> than clearing them without any interaction."

I left the "prompt" here with introduction of the "dialog box", in the following

(In reply to Ian Neal from comment #10)
> I was using "prompts" as being "prompted for information" rather than
> "prompt boxes". If we do not use "prompts" then it should be "dialog boxes"
> with the word "any" otherwise change it to "a dialog box".

using "dialog box" only and expanding vs. "immediately" a bit.

> I use IMAP and I've never really noticed it, but it is across a LAN so
> probably hard to notice anyway. If it only works for IMAP and not for POP
> then might be worth making that distinction.

Definitely not for POP accounts, putting disk data into a disk cache indeed wouldn't make much sense...

> It is more to do with British English vs American English. British tend to
> use web site, American website.

That's the case for the en-GB locale ("web site"), thus let's keep it "username" here for consistency.

Comment 12

[Ian Neal]

Comment on attachment 714354 [details] [diff] [review]
Proposed patch (v3)

>+++ b/suite/locales/en-US/chrome/common/help/using_priv_help.xhtml

>+      <td>Cache</td>
>+      <td>The cache is a <em>short-term store</em> for web pages and other
>+        data (like e-mail attachments for IMAP accounts or remote images in
>+        messages) to avoid having these items being requested again from the
>+        server for pages which you have just recently visited. It may contain
The bit that says "for pages which you have just recently visited" does not make sense for other data, so potential remove or reword to make sense.

>+        data up to the limit specified in the
>+        <a href="cs_nav_prefs_advanced.xhtml#cache">Cache preferences</a>.</td>

f=me for the moment as the rest of the changes are great :)

Comment 13

[rsx11m]

(In reply to Ian Neal from comment #12)
> The bit that says "for pages which you have just recently visited" does not
> make sense for other data, so potential remove or reword to make sense.

I can make it "for just recently accessed data" which is neutral towards the type of data but less personal (also given that it may not be data you have directly requested from the server but which happened to come with it from third parties).

Comment 14

[Ian Neal]

(In reply to rsx11m from comment #13)
> (In reply to Ian Neal from comment #12)
> > The bit that says "for pages which you have just recently visited" does not
> > make sense for other data, so potential remove or reword to make sense.
> 
> I can make it "for just recently accessed data" which is neutral towards the
> type of data but less personal (also given that it may not be data you have
> directly requested from the server but which happened to come with it from
> third parties).

Yes, that sounds okay.

Comment 15

[rsx11m]

Attachment: Proposed patch (v4)

I've come up with a slightly different phrasing in this patch, to avoid that "data" is followed by "data" (and which kind of data we refer to is introduced at the beginning of the sentence already):

> +      <td>The cache is a <em>short-term store</em> for web pages and other
> +        data (like e-mail attachments for IMAP accounts or remote images in
> +        messages) to avoid having these items being requested again from the
> +        server if they were just recently accessed. The cache on your disk
> +        may contain data up to the limit specified in the
> +        <a href="cs_nav_prefs_advanced.xhtml#cache">Cache preferences</a>.</td>

I've changed "It" (referring to the cache) at the beginning of the next sentence to disambiguate what it refers to, and "cache on your disk" retains the personal/local context.

I'm looking forward to an r+ in this round.  ;-)

Comment 16

[Ian Neal]

Comment on attachment 717678 [details] [diff] [review]
Proposed patch (v4)

r=me

Comment 17

[rsx11m]

Thanks Ian, push for trunk please.

Comment 18

[Philip Chee]

Pushed to comm-central:
http://hg.mozilla.org/comm-central/rev/994ffd181f36