847182 - Extend Glossary with new Privacy & Security terms

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[rsx11m]

Recent additions to the Privacy & Security and Advanced preference panes (both for the actual panes but also in Help contents) introduced terms not listed in glossary.xhtml yet. Those should be added and linked in help-glossary.rdf.

Comment 1

[rsx11m]

Attachment: Proposed patch

I don't know if you want all of those, but here comes the patch.  :-)

This introduces the following new terms to the glossary:
* Do Not Track - bug 631566, bug 844823
* fingerprinting (browser) - bug 844823
* Malware - bug 631566 (link added by bug 844823)
* private data - bug 416234
* safe browsing - bug 631566
* user tracking - bug 631566, bug 844823
* web application - bug 771534

I didn't add any external website links (e.g., http://donnottrack.us or http://www.mozilla.org/dnt for user tracking) as they tend to change.

The patch also modifies the following entries in glossary.xhtml:
* cookie - link to "third-party cookie" rather than "foreign cookie" as this is
  the more established name and also used in the preferences UI
* fingerprint (certificate) - to distinguish it from browser fingerprinting
* foreign cookie - now a "See " link to "third-party cookie"
* implicit consent - added a "See also" link to "user tracking"
* third-party cookie - got text from "foreign cookie", moved link to "website"
  to the first occurrence of that term. 

Changes in help-index1.rdf:

The "foreign cookies" entry was moved to "third-party cookies" to match glossary changes, and this also matches the actual section title now.

I've changed "safe browsing" and "user tracking" entries, pointing to the respective preferences, to "safe browsing preferences" and "user tracking preferences" to distinguish them from the glossary entries.

Comment 2

[Stefan [:stefanh]]

Thanks, I'll look at the patch over the weekend (slow as usual). I see that "web application" is used in a few places in our documentation and you might want to link to the glossary term in a few places (I didn't checked the other new terms).

Comment 3

[rsx11m]

I'll have a look and may post an updated patch Friday evening. There are already some independent explanations in the recent additions, thus I don't think that those would need to be linked up to the glossary in addition to that (and "user tracking" links to the new section in bug 844823 which is more comprehensive).

Comment 4

[rsx11m]

Quick inventory:
* Do Not Track - no hits, further background will be provided by bug 844823
* fingerprinting - no hits, further background will be provided by bug 844823
* malware - link to glossary will be added by bug 844823
* private data - full section in using_priv_help.xhtml#types_of_private_data
* safe browsing - own section in privsec_help.xhtml#safe_browsing
* user tracking - gets own section in privacy_help.xhtml (bug 844823)
* web application - several hits in cs_nav_prefs_advanced.xhtml (bug 771534),
  cs_nav_prefs_navigator.xhtml, and developer_tools.xhtml; so that's indeed the
  best candidate for adding some links to the new terms in the glossary.

Comment 5

[rsx11m]

Attachment: Proposed patch (v2)

Following additions (no other changes relative to attachment 721007 [details] [diff] [review]):

* cs_nav_prefs_advanced.xhtml - rephrased and extended the new introductory
  paragraph from bug 771534 and introduced "web application" (with link to the
  glossary) as a general term there, with "offline" being the special case.

* cs_nav_prefs_navigator.xhtml - linked the first instance of "web application"
  in "Helper Applications" to the glossary; I've removed the reference to Live
  Bookmarks, they are no longer in the glossary (or anywhere else in Help) and
  the part removed was already commented out, thus not visible anyway.

* developer_tools.xhtml - linked the first instance of "web application" in the
  "Tools and Development" section; also made this and another instance of "Web"
  lower case to match the other instances.

* privsec_help.xhtml - linked "malware" to the glossary; this part was moved
  over from the patch in bug 844823 so that both patches are self-contained now
  (no overlap = no bitrotting either way).

I should be around most of the time over the weekend for feedback or changes.

Comment 6

[Stefan [:stefanh]]

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

Sorry for being so slow... (not sure why the weekend ended that fast)

Looks very good. f+ since we need to settle the things below and I'd like a new patch that I can re-run.


>+<dt id="malware">Malware</dt><dd>Short for <q><u>Mal</u>icious
>+  Soft<u>ware</u></q> and a general term for a variety of software designed
>+  to disrupt computer operation, gather sensitive information, or gain access
>+  to your computer. They can be distributed by infected <a href="#web_page">web
>+  pages</a> or as attachments to e-mail messages. Examples include viruses,
>+  worms, trojans, spyware, or adware. Malware may redistribute itself by
>+  sending out e-mail messages to infect other computers.</dd>
>+

We mix e-mail and email through the help documentation. But 'email' is more common (145) than 'e-mail' (11). So let us use 'email' here :-)

> <dt id="master_key">master key</dt><dd>A symmetric key used by
>   <a href="#certificate_manager">Certificate Manager</a> to encrypt
>   information. For example, <a href="#password_manager">Password Manager</a>
>   uses Certificate Manager and your master key to encrypt email passwords,
>   website passwords, and other stored sensitive information. See also
>   <a href="#symmetric_encryption">symmetric encryption</a>.</dd>
> 
> <dt id="master_password">master password</dt><dd>A password used by
>@@ -519,16 +536,24 @@
>   that requires you to download new messages to your local
>   computer&mdash;although you can choose to leave copies on the server. With
>   POP, you can store all your messages, including sent mail, drafts, and custom
>   folders, on one computer only. By contrast,
>   <a href="#imap">IMAP</a> allows you to permanently store all your messages
>   and any changes to them on the server, where you can access them from any
>   computer. Most <a href="#isp">ISPs</a> currently support POP.</dd>
> 
>+<dt id="private_data">private data</dt><dd>Any type of data that is stored by
>+  &brandShortName; locally on your computer as a result from visiting a
>+  <a href="#website">website</a> or other activity such as reading e-mails.
>+  Examples include your browsing history, form data, <a href="#cache">cache</a>
>+  contents, <a href="#cookie">cookies</a>, stored
>+  <a href="#password-based_authentication">passwords</a>, or offline data from
>+  <a href="#web_application">web applications</a>.</dd>
>+

I wonder if we should add 'private data'. Is this really a 'term' that you can define? If we linked to it somewhere from the documentation it would make sense (it would be in the right context), but in this case the glossary functions as a dictionary. Maybe it works, though - but I would like to hear your view on it.

> <dt id="private_key">private key</dt><dd>One of a pair of
>   <a href="#key">keys</a> used in public-key cryptography. The private key is
>   kept secret and is used to decrypt data that has been encrypted with the
>   corresponding public key.</dd>
> 
> <dt id="proxy">proxy</dt><dd>An intermediary or <q>go-between</q> program that
>   acts as both a <a href="#server">server</a> and a
>   <a href="#client">client</a> for the purpose of making requests on behalf of
>@@ -556,16 +581,23 @@
>   <a href="#certificate_authority">certificate authority (CA)</a> with a
>   self-signed certificate at the top of a
>   <a href="#certificate_chain">certificate chain</a>. See also
>   <a href="#subordinate_ca">subordinate CA</a>.</dd>
> 
> <dt id="rss">RSS (Really Simple Syndication)</dt><dd>An <a href="#xml">XML</a>
>   data format for web <a href="#feed">feeds</a>.</dd>
> 
>+<dt id="safe_browsing">safe browsing</dt><dd>Protection against common threats
>+  from <a href="#malware">Malware</a> and <a href="#phishing">Phishing</a> by
>+  checking each <a href="#web_page">web page</a> against a list of reported
>+  websites. If the web page you are about to visit has been reported as
>+  containing malicious content, &brandShortName; prevents it from loading
>+  and shows a warning instead.</dd>
>+
> <dt id="search_engine">search engine</dt><dd>A web-based program that allows
>   users to search for and retrieve specific information from the
>   <a href="#world_wide_web">World Wide Web (WWW)</a>. The search engine may
>   search the full text of web documents or a list of keywords, or use
>   librarians who review web documents and index them manually for retrieval.
>   Typically, the user types a word or phrase, also called a query, into a
>   search box, and the search engine displays links to relevant web pages.</dd>
> 
>@@ -716,18 +748,24 @@
> <dt id="tcp_ip">TCP/IP (Transmission Control Protocol/Internet
>   Protocol)</dt><dd>A Unix protocol used to connect computers running a variety
>   of operating systems. TCP/IP is an essential Internet protocol and has become
>   a global standard.</dd>
> 
> <dt id="theme">theme</dt><dd>A type of <a href="#add-on">add-on</a> that changes
>   the appearance of &brandShortName;.</dd>
> 
>-<dt id="third-party_cookie">third-party cookie</dt><dd>See
>-  <a href="#foreign_cookie">foreign cookie</a>.</dd>
>+<dt id="third-party_cookie">third-party cookie</dt><dd>A
>+  <a href="#cookie">cookie</a> from one <a href="#website">website</a> that
>+  gets stored on your computer when you visit a different website. Sometimes a
>+  website displays content that is hosted on another website. That content can
>+  be anything from an image to text or an advertisement. The second website
>+  that hosts such elements also has the ability to store a cookie in your
>+  browser, even though you don&apos;t visit it directly. Also known as
>+  <q>foreign cookie</q>.</dd>
> 
> <dt id="tls">TLS</dt><dd>Transport Layer Security (TLS) is the new Internet
>   Engineering Task Force (IETF) standard based on SSL (Secure Sockets Layer).
>   See also <a href="#ssl">SSL</a> and
>   <a href="#encryption">encryption</a>.</dd>
> 
> <dt id="token">token</dt><dd>See <a href="#security_device">security
>   device</a>.</dd>
>@@ -749,16 +787,33 @@
> <dt id="url">URL (Uniform Resource Locator)</dt><dd>The standardized address
>   that tells your browser how to locate a file or other resource on the Web.
>   For example: <tt>http://www.mozilla.org.</tt> You can type URLs into the
>   browser&apos;s <a href="#location_bar">Location Bar</a> to access
>   <a href="#web_page">web pages</a>. URLs are also used in the links on web
>   pages that you can click to go to other web pages. Also known as an Internet
>   address or Web address.</dd>
> 
>+<dt id="user_tracking">user tracking</dt><dd>A variety of methods that
>+  <a href="#website">websites</a>, advertisers, and others use to learn about
>+  your web browsing behavior. This includes information about what sites you
>+  visit, things you like or dislike, and purchase. They often use this

Hmm, I think 'and purchase' needs a re-phrase here. You have 'what sites' (should be 'what sites you have visited', I think) and 'things you like...' and then you end with 'and purchase'. I think the "," makes it separated from the 'like or dislike' part - at least for me. Maybe 'and what you have purchased' or 'and your purchases' or 'and your purchase history'.

Comment 7

[rsx11m]

(In reply to Stefan [:stefanh] from comment #6)
> I wonder if we should add 'private data'. Is this really a 'term' that you
> can define? If we linked to it somewhere from the documentation it would
> make sense (it would be in the right context), but in this case the glossary
> functions as a dictionary. Maybe it works, though - but I would like to hear
> your view on it.

That was one of the cases where I was struggling myself if it's really useful, given that it's not an established term, and we have a full section pointed to from the Private Data preferences. Since you seem to tend the same way, let's remove that part. There will be sufficient hits for "Private Data" from the preferences and tutorial sections.

> Hmm, I think 'and purchase' needs a re-phrase here. You have 'what sites'
> (should be 'what sites you have visited', I think) and 'things you like...'
> and then you end with 'and purchase'. I think the "," makes it separated
> from the 'like or dislike' part - at least for me. Maybe 'and what you have
> purchased' or 'and your purchases' or 'and your purchase history'.

I'll look into it. I may have grabbed that from the Firefox FAQ page and possibly screwed it up during copy-pasting.

New patch should be coming up soon'ish.

Comment 8

[rsx11m]

Attachment: Proposed patch (v3)

Comment #6 addressed with some additional instances of s/e-mail/email/ fixed.

Comment 9

[rsx11m]

Attachment: Proposed patch (v4)

Relative to attachment 723216 [details] [diff] [review], this patch has one additional hunk in privsec_help.xhtml:

Now that bug 844823 has added the tutorial section, I've rephrased the introductory paragraph for the User Tracking preference pane. Its version initially provided with bug 631566 was in essence what's now in the glossary, missing on the other hand a more specific mentioning of "Do Not Track".

I'm linking now the two major terms to the glossary and also explicitly provide the name of the new section with its link. In addition, Do Not Track is usually capitalized in the project page and the standards draft and without quotes, thus I've changed that and left the quotes only with the first occurrence.

Everything else is unchanged.

Comment 10

[rsx11m]

Attachment: Proposed patch (v5)

A couple of paragraphs rephrased and/or simplified as discussed, along with a few more details added. That should be it from my side now.

Comment 11

[Stefan [:stefanh]]

Comment on attachment 725769 [details] [diff] [review]
Proposed patch (v5)

Nice work - just 2 things:

>+<dt id="do_not_track">Do Not Track</dt><dd>A mechanism that allows users
>+  to opt out of (or consent to) <a href="#user_tracking">tracking</a> by
>+  <a href="#websites">websites</a> that they do not explicitly visit but
>+  which are embedded into <a href="#web_page">web pages</a>. This includes
>+  advertisers and analytics services as well as social websites.
>+  &brandShortName; supports sending <q>Do Not Track</q> requests, but
>+  websites are not obligated to honor those.</dd>
>+

I'd say something like this (I don't think we need more):

"A mechanism that allows users to inform websites that they do not want to be tracked by third-party websites and web applications. &brandShortName; supports sending <q>Do Not Track</q> requests, but websites are not obligated to honor those."

A bit more techy (we have an entry for HTTP in the glossary):
"A mechanism that allows users to inform websites that they do not want to be tracked by third-party websites and web applications. A users tracking preference is included in the HTTP header and sent to the website. &brandShortName; supports sending <q>Do Not Track</q> requests, but websites are not obligated to honor those."


> <h3>User Tracking</h3>
> 
> <p>These settings allow you to communicate your tracking preferences to
>-  websites.
>-  <q><a href="privacy_help.xhtml#why_and_how_are_websites_tracking_me">Tracking</a></q>
>-  is a term that includes many different methods that websites, advertisers,
>-  and others use to learn about your web browsing behavior. This includes
>-  information about what sites you visit, things you like or dislike, and
>-  purchase, thus affecting your privacy. They often use this information to
>-  show ads, products, or services specifically targeted to you. The following
>-  options are available in this section:</p>
>+  websites. <q><a href="glossary.xhtml#user_tracking">Tracking</a></q> refers
>+  to websites (including advertisers, analytics providers, and social sites)
>+  collecting and analyzing comprehensive data on your web browsing patterns,
>+  thus affecting your privacy. For more information on this topic, see
>+  <a href="privacy_help.xhtml#why_and_how_are_websites_tracking_me">Why and How
>+  Are Websites Tracking Me?</a> The <q><a href="glossary.xhtml#do_not_track">Do
>+  Not Track</a></q> technology allows you to tell a website whether or not you
>+  agree to tracking. The following options are available in this section:</p>

Hmm, I'm quite convinced that "Are" in Why and How Are Websites Tracking Me?" should be all lower-case (look at other headings). Could be fixed in another bug if you want.

Looking at what we say about Do Not Track here and the context I'm not 100% convinced that the glossary term will give any additional information. So perhaps we shouldn't link to the glossary term below? Maybe the more techy version gives a bit more info, though. Your choice, just raising the question.

Comment 12

[Stefan [:stefanh]]

(In reply to Stefan [:stefanh] from comment #11)
> Comment on attachment 725769 [details] [diff] [review]
> Proposed patch (v5)
> 
> Nice work - just 2 things:
> 
 Oops, it became 3 :-)

Comment 13

[rsx11m]

(In reply to Stefan [:stefanh] from comment #11)
> A bit more techy (we have an entry for HTTP in the glossary):
> "A mechanism that allows users to inform websites that they do not want to
> be tracked by third-party websites and web applications. A users tracking
> preference is included in the HTTP header and sent to the website.
> &brandShortName; supports sending <q>Do Not Track</q> requests, but websites
> are not obligated to honor those."

I like that version. It adds further information on the actual implementation and doesn't repeat what we are saying in User Tracking later.

> >+  <a href="privacy_help.xhtml#why_and_how_are_websites_tracking_me">Why and How
> >+  Are Websites Tracking Me?</a> The <q><a
> Hmm, I'm quite convinced that "Are" in Why and How Are Websites Tracking
> Me?" should be all lower-case (look at other headings). Could be fixed in
> another bug if you want.

I was wondering as well but found the section title "What Are Cookies..." above it. Then there is also "What Are Bookmarks?" elsewhere, thus I kept it consistent.

I agree that there are different styles which classes of words should be capitalized and which aren't, but that should be done consistently with all headings in the Help contents (i.e., that indeed would be a new bug). No Change.

> Looking at what we say about Do Not Track here and the context I'm not 100%
> convinced that the glossary term will give any additional information. So
> perhaps we shouldn't link to the glossary term below? Maybe the more techy
> version gives a bit more info, though. Your choice, just raising the
> question.

I'll keep it along with the "techy" version, given that the glossary term in that case adds the fact that it's part of the HTTP request.

New patch coming up soon.

Comment 14

[rsx11m]

Attachment: Proposed patch (v6)

Techy version of glossary entry from comment #11 added.

(In reply to rsx11m from comment #13)
> I was wondering as well but found the section title "What Are Cookies..."
> above it. Then there is also "What Are Bookmarks?" elsewhere, thus I kept it
> consistent.

Well, in that case I have also modified the secondary title in privacy_help.xhtml to match its Third-Party Cookies counterpart:

> @@ -195,17 +195,17 @@
> -<h3>What are the Mechanisms of User Tracking?</h3>
> +<h3>What Are the Mechanisms of User Tracking?</h3>

As another fix, I've hooked up the term "web applications" added to the "Notes:" bullet list for privsec_xhtml.html with v5 to the glossary which I missed there.

Comment 15

[Stefan [:stefanh]]

Comment on attachment 725893 [details] [diff] [review]
Proposed patch (v6)


>+<dt id="do_not_track">Do Not Track</dt><dd>A mechanism that allows users
>+  to inform <a href="#website">websites</a> that they do not want to be
>+  <a href="#user_tracking">tracked</a> by third-party websites and
>+  <a href="#web_application">web applications</a>. A user&apos; tracking
>+  preferences is included in the <a href="#http">HTTP header</a> and sent

Make that "<a href="#http">HTTP</a> header" since otherwise users might expect an explanation of the term "HTTP header".

Comment 16

[rsx11m]

Attachment: Final patch (v7)

Done, and this is now ready to be pushed on trunk (phew!).

Comment 17

[rsx11m]

(In reply to Stefan [:stefanh] from comment #11)
> Hmm, I'm quite convinced that "Are" in Why and How Are Websites Tracking
> Me?" should be all lower-case (look at other headings).

To follow up on this question, "are" is here the present plural of "be" and used as an auxiliary verb (says Merriam-Webster). In the style guides I've looked up, verbs in headings are capitalized, thus I'd think that we are doing it right here (though I've seen titles with lower-case "is" and "are").

Comment 18

[rsx11m]

I've spun off bug 852318 on the section-heading capitalization as we are clearly not doing it consistently with a variety of words (I'm not sure if it's worth the effort, but at least it's on file now).

Comment 19

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/comm-central/rev/424c9e902a05