Merge pull request #4244 from rtfd/davidfischer/ad-blocking-details-docs

Add a page detailing ad blocking

docs/advertising/ad-blocking.rst

@@ -0,0 +1,71 @@
+Ad blocking
+===========
+
+Ad blockers fulfill a legitimate need
+to mitigate the significant downsides of advertising
+from tracking across the internet,
+security implications of third-party code,
+and impacting the UX and performance of sites.
+
+At Read the Docs, we specifically didn't want those things.
+That's why we built the our :doc:`Ethical Ad initiative <ethical-advertising>`
+with only relevant, unobtrusive ads that respect your privacy
+and don't do creepy behavioral targeting.
+
+Advertising is the single largest source of funding for Read the Docs.
+To keep our operations sustainable, we ask that you either
+:ref:`allow our Ethical Ads <advertising/ad-blocking:Allowing Ethical Ads>`
+or :ref:`go ad-free <advertising/ad-blocking:Going ad-free>`.
+
+
+Allowing Ethical Ads
+--------------------
+
+If you use AdBlock or AdBlockPlus
+and you allow `acceptable ads`_ or `privacy-friendly acceptable ads`_
+then you're all set.
+Advertising on Read the Docs complies with both of these programs.
+
+If you prefer not to allow acceptable ads
+but would consider allowing `ads that benefit open source`_,
+please consider subscribing to either the wider **Open Source Ads list**
+or simply the **Read the Docs Ads list**.
+
+.. note::
+
+    Because of the way Read the Docs is structured
+    where docs are hosted on many different domains,
+    adding a normal ad block exception
+    will only allow that single domain not Read the Docs as a whole.
+
+.. _acceptable ads: https://adblockplus.org/en/acceptable-ads
+.. _privacy-friendly acceptable ads: https://adblockplus.org/en/acceptable-ads#privacy-friendly-acceptable-ads
+.. _ads that benefit open source: https://ads-for-open-source.readthedocs.io/en/latest/
+
+
+Going ad-free
+-------------
+
+Users can go completely ad-free
+by becoming a `Gold Member <https://readthedocs.org/accounts/gold/>`_
+or a `Supporter <https://readthedocs.org/sustainability/#donations>`_.
+Thank you for supporting Read the Docs.
+
+
+Statistics and data
+-------------------
+
+It can be really hard to find good data on ad blocking.
+In the spirit of transparency,
+here is the data we have on ad blocking at Read the Docs.
+
+* `32% of Read the Docs users use an ad blocker <https://blog.readthedocs.com/ads-and-adblocking/>`_
+* Of those, `a little over 50% allow acceptable ads <https://blog.readthedocs.com/ad-blocker-update/>`_
+* Read the Docs users running ad blockers click on ads at about the same rate
+  as those not running an ad blocker.
+* Comparing with our server logs,
+  roughly 28% of our hits did not register a Google Analytics (GA) pageview
+  due to an ad blocker, privacy plugin, disabling JavaScript, or another reason.
+* Of users who do not block GA,
+  about 6% opt out of analytics on Read the Docs by enabling
+  :ref:`Do Not Track <privacy-policy:Do Not Track>`.

docs/advertising-details.rst → docs/advertising/advertising-details.rst

@@ -121,7 +121,7 @@ Analytics
 
 Analytics are a sensitive enough issue that they require their own section.
 In the spirit of full transparency, Read the Docs uses Google Analytics (GA).
-We go into a bit of detail on our use of GA in our :doc:`privacy-policy`.
+We go into a bit of detail on our use of GA in our :doc:`/privacy-policy`.
 
 GA is a contentious issue inside Read the Docs and in our community.
 Some users are very sensitive and privacy conscious to usage of GA.
@@ -132,7 +132,7 @@ our own goals.
 
 We have taken steps to address some of the privacy concerns surrounding GA.
 These steps apply both to analytics collected by Read the Docs and when
-:doc:`authors enable analytics on their docs <guides/google-analytics>`.
+:doc:`authors enable analytics on their docs </guides/google-analytics>`.
 
 * Users can opt-out of analytics by using the Do Not Track feature of their browser.
 * Read the Docs instructs Google to anonymize IP addresses sent to them.

docs/ethical-advertising.rst → docs/advertising/ethical-advertising.rst

@@ -9,10 +9,10 @@ and we're calling it **Ethical Ads**.
 **Ethical Ads respect users while providing value to advertisers.**
 We don't track you, sell your data, or anything else.
 We simply show ads to users, based on the content of the pages you look at.
-We also give 10% of our ad space to :ref:`community projects <ethical-advertising:Community Ads>`,
+We also give 10% of our ad space to :ref:`community projects <advertising/ethical-advertising:Community Ads>`,
 as our way of saying thanks to the open source community.
 
-We talk a bit below about :ref:`our worldview on advertising <ethical-advertising:Our Worldview>`,
+We talk a bit below about :ref:`our worldview on advertising <advertising/ethical-advertising:Our Worldview>`,
 if you want to know more.
 
 .. important::
@@ -28,9 +28,9 @@ and we value your feedback.
 If you ever want to reach out about this effort,
 feel free to `shoot us an email <mailto:[email protected]>`_.
 
-You can :ref:`opt out <ethical-advertising:Opting out>` of having paid ads on your projects,
+You can :ref:`opt out <advertising/ethical-advertising:Opting out>` of having paid ads on your projects,
 or seeing paid ads if you want.
-You will still see :ref:`community ads <ethical-advertising:Community Ads>`,
+You will still see :ref:`community ads <advertising/ethical-advertising:Community Ads>`,
 which we run for free that promote community projects. 
 
 Our Worldview
@@ -131,13 +131,14 @@ Opting Out
 
 We have added multiple ways to opt out of the advertising on Read the Docs.
 
-Users can go ad-free for as long as they are logged-in
-by becoming a `Gold Member of Read the Docs <https://readthedocs.org/accounts/gold/>`_.
+Users can go ad-free
+by becoming a `Gold Member <https://readthedocs.org/accounts/gold/>`_
+or a `Supporter <https://readthedocs.org/sustainability/#donations>`_.
 
 Users can opt out of seeing paid advertisements on documentation pages:
 
 * Go to the drop down user menu in the top right of the Read the Docs dashboard and clicking **Settings** (https://readthedocs.org/accounts/edit/).
-* On the **Details** tab, you can deselect **See paid advertising**.
+* On the **Advertising** tab, you can deselect **See paid advertising**.
 
 Project owners can also disable advertisements for their projects. You can change these options:
 

docs/advertising/index.rst

@@ -0,0 +1,33 @@
+Advertising
+===========
+
+Advertising is the single largest source of funding for Read the Docs.
+It allows us to:
+
+.. Updated: June 2018
+
+- Serve over **35 million pages** of documentation per month
+- Serve over **40 TB** of documentation per month
+- Host over **80,000 open source projects** and support over **100,000 users**
+- Pay a :doc:`small team </team>` of dedicated full-time staff
+
+Many advertising models involve tracking users around the internet,
+selling their data, and privacy intrusion in general.
+Instead of doing that, we built an :doc:`Ethical Advertising <ethical-advertising>` model
+that respects user privacy.
+
+We recognize that advertising is not for everyone.
+You may :ref:`opt out of paid advertising <advertising/ethical-advertising:Opting Out>`
+-- you will still see :ref:`community ads <advertising/ethical-advertising:Community Ads>` --
+or you can go ad-free by `becoming a Gold Member`_ or a `Supporter`_ of Read the Docs.
+
+.. _becoming a Gold Member: https://readthedocs.org/accounts/gold/
+.. _Supporter: https://readthedocs.org/sustainability/#donations
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Advertising at Read the Docs
+
+    ethical-advertising
+    advertising-details
+    ad-blocking

docs/index.rst

@@ -58,8 +58,7 @@ Information about development is also available:
    gsoc
    code-of-conduct
    privacy-policy
-   ethical-advertising
-   advertising-details
+   advertising/index
    sponsors
    open-source-philosophy
    story

docs/privacy-policy.rst

@@ -140,7 +140,7 @@ We **do** host advertising on Documentation Sites.
 This advertising is first-party advertising hosted by Read the Docs.
 We **do not** run any code from advertisers and all ad images are hosted
 on Read the Docs' servers. For more details, see our document on
-:doc:`advertising-details`.
+:doc:`advertising/advertising-details`.
 
 We may use User Personal Information with your permission,
 so we can perform services you have requested.
@@ -166,12 +166,13 @@ and we encourage you to check back periodically.
 Payment processing
 ++++++++++++++++++
 
-Should you choose to donate to Read the Docs, purchase a `Gold subscription`_,
+Should you choose to become a `Supporter`_, purchase a `Gold Membership`_,
 or become a subscriber to Read the Docs' commercial hosting product,
 your payment information and details will be processed by Stripe.
 Read the Docs does not store your payment information.
 
-.. _Gold subscription: https://readthedocs.org/accounts/gold/
+.. _Gold Membership: https://readthedocs.org/accounts/gold/
+.. _Supporter: https://readthedocs.org/sustainability/
 
 Site monitoring
 +++++++++++++++

readthedocs/core/static-src/core/js/doc-embed/sponsorship.js

@@ -175,17 +175,15 @@ function adblock_admonition() {
     console.log(' - never sell user data to advertisers or other 3rd parties');
     console.log(' - only show advertisements of interest to developers');
     console.log('Read more about our approach to advertising here: https://docs.readthedocs.io/en/latest/ethical-advertising.html');
-    console.log('Read more about Ads for Open Source: https://ads-for-open-source.readthedocs.io');
-    console.log('Or go ad-free: https://readthedocs.org/sustainability/');
-    console.log('%cPlease whitelist Read the Docs on your adblocker using the following filter:', 'font-size: 2em');
-    console.log('https://ads-for-open-source.readthedocs.io/en/latest/_static/lists/readthedocs-ads.txt');
+    console.log('%cPlease allow our Ethical Ads or go ad-free:', 'font-size: 2em');
+    console.log('https://docs.readthedocs.io/en/latest/advertising/ad-blocking.html');
     console.log('--------------------------------------------------------------------------------------');
 }
 
 function adblock_nag() {
     // Place an ad block nag into the sidebar
     var placement = create_sidebar_placement();
-    var unblock_url = 'https://ads-for-open-source.readthedocs.io/';
+    var unblock_url = 'https://docs.readthedocs.io/en/latest/advertising/ad-blocking.html#allowing-ethical-ads';
     var ad_free_url = 'https://readthedocs.org/sustainability/';
     var container = null;