Skip to content

Commit 8432800

Browse files
davidfischerdavidfischer
authored
Merge pull request #3955 from davidfischer/docs-advertising-details
Add advertising details docs
2 parents 4f6123b + d703f1c commit 8432800

File tree

4 files changed

+148
-21
lines changed

4 files changed

+148
-21
lines changed

‎docs/advertising-details.rst

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
Advertising Details
2+
===================
3+
4+
.. NOTE: This document is linked from:
5+
.. https://media.readthedocs.org/javascript/readthedocs-analytics.js
6+
7+
Read the Docs largely funds our operations and development through advertising.
8+
However, we aren't willing to compromise our values, document authors,
9+
or site visitors simply to make a bit more money.
10+
That's why we created our
11+
:doc:`ethical advertising <ethical-advertising>` initiative.
12+
13+
We get a lot of inquiries about our approach to advertising which range
14+
from questions about our practices to requests to partner.
15+
The goal of this document is to shed light on the advertising industry,
16+
exactly what we do for advertising, and how what we do is different.
17+
If you have questions or comments,
18+
`send us an email <mailto:[email protected]>`_
19+
or `open an issue on GitHub <https://github.com/rtfd/readthedocs.org/issues>`_.
20+
21+
22+
Other ad networks' targeting
23+
----------------------------
24+
25+
Some ad networks build a database of user data in order to predict the types
26+
of ads that are likely to be clicked.
27+
In the advertising industry, this is called *behavioral targeting*.
28+
This can include data such as:
29+
30+
* sites a user has visited
31+
* a user's search history
32+
* ads, pages, or stories a user has clicked on in the past
33+
* demographic information such as age, gender, or income level
34+
35+
Typically, getting a user's page visit history is accomplished by the use of trackers
36+
(sometimes called beacons or pixels).
37+
For example, if a site uses a tracker from an ad network and a user visits that site,
38+
the site can now target future advertising to that user -- a known past visitor --
39+
with that network. This is called *retargeting*.
40+
41+
Other ad predictions are made by grouping similar users
42+
together based on user data using machine learning.
43+
Frequently this involves an advertiser uploading personal data on users
44+
(often past customers of the advertiser)
45+
to an ad network and telling the network to target similar users.
46+
The idea is that two users with similar demographic information
47+
and similar interests would like the same products.
48+
In ad tech, this is known as *lookalike audiences* or *similar audiences*.
49+
50+
Understandably, many people have concerns about these targeting techniques.
51+
The modern advertising industry has built enormous value by centralizing
52+
massive amounts of data on as many people as possible.
53+
54+
55+
Our targeting details
56+
---------------------
57+
58+
**Read the Docs doesn't use the above techniques**.
59+
Instead, we target based solely upon:
60+
61+
* Details of the page where the advertisement is shown including:
62+
63+
* The name, keywords, or programming language associated with the project being viewed
64+
* Content of the page (eg. H1, title, theme, etc.)
65+
* Whether the page is being viewed from a mobile device
66+
67+
* General geography
68+
69+
* We allow advertisers to target ads to a list of countries or to exclude
70+
countries from their advertising.
71+
* We geolocate a user's IP address to a country when a request is made.
72+
73+
Read the Docs uses GeoLite2 data created by `MaxMind <http://maxmind.com>`_.
74+
75+
.. note::
76+
77+
We are considering expanding geographic targeting in the USA and Canada.
78+
Because the USA and Canada are so large, we are considering allowing ads to be
79+
targeted to a state or province or to a major metro area (DMA).
80+
This document will be updated if that happens.
81+
82+
83+
.. _advertising-analytics:
84+
85+
Analytics
86+
---------
87+
88+
Analytics are a sensitive enough issue that they require their own section.
89+
In the spirit of full transparency, Read the Docs currently uses Google Analytics (GA).
90+
91+
GA is a contentious issue inside Read the Docs and in our community.
92+
Some users are very sensitive and privacy conscious to usage of GA.
93+
Some authors want their own analytics on their docs to see the usage their docs get.
94+
The developers at Read the Docs understand that different users have different priorities
95+
and we try to respect the different viewpoints as much as possible while also accomplishing
96+
our own goals.
97+
98+
Advertisers ask us questions that are easily answered with an analytics solution like
99+
"how many users do you have in Switzerland browsing Python docs?". We need to be able
100+
to easily get this data. We also use data from GA for some development decisions such
101+
as what browsers to support (or not) or how much usage a particular page or feature gets.
102+
103+
We have taken steps to address some of the privacy concerns.
104+
Read the Docs instructs Google to anonymize IPs sent to them before they are stored.
105+
106+
Alternatives
107+
~~~~~~~~~~~~
108+
109+
We are always exploring our options with respect to analytics.
110+
There are alternatives but none of them are without downsides.
111+
Some alternatives are:
112+
113+
* Run a different cloud analytics solution from a provider other than Google
114+
(eg. Parse.ly, Matomo Cloud, Adobe Analytics).
115+
We priced a couple of these out based on our load and they are very expensive.
116+
They also just substitute one problem of data sharing with another.
117+
* Send data to GA (or another cloud analytics provider) on the server side and
118+
strip or anonymize personal data such as IPs before sending them.
119+
This would be a complex solution and involve additional infrastructure,
120+
but it would have many advantages. It would result in a loss of data on
121+
"sessions" and new vs. returning visitors which are of limited value to us.
122+
* Run a local JavaScript based analytics solution (eg. Matomo community).
123+
This involves additional infrastructure that needs to be always up.
124+
Frequently there are very large databases associated with this.
125+
Many of these solutions aren't built to handle Read the Docs' load.
126+
* Run a local analytics solution based on web server log parsing.
127+
This has the same infrastructure problems as above while also
128+
not capturing all the data we want (without additional engineering) like the
129+
programming language of the docs being shown or
130+
whether the docs are built with Sphinx or something else.

‎docs/ethical-advertising.rst

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,6 @@ or seeing paid ads if you want.
3333
You will still see :ref:`community ads <community-ads>`,
3434
which we run for free that promote community projects.
3535

36-
We have gone into more detail about our views in our `blog post <https://blog.readthedocs.com/ads-on-read-the-docs/>`_ about this topic.
37-
Eric Holscher, one of our co-founders `talks a bit more <http://ericholscher.com/blog/2016/aug/31/funding-oss-marketing-money/>`_ about funding open source this way on his blog.
38-
3936
.. _ethical-info:
4037

4138
Our worldview
@@ -94,6 +91,21 @@ in a way that makes us feel good.
9491

9592
.. _fake ad clicks: https://en.wikipedia.org/wiki/Click_fraud
9693

94+
Additional details
95+
------------------
96+
97+
* We have additional documentation on the
98+
:doc:`technical details of our advertising <advertising-details>`
99+
including our use of analytics.
100+
* We have an `advertising FAQ`_ written for advertisers.
101+
* We have gone into more detail about our views in our
102+
`blog post <https://blog.readthedocs.com/ads-on-read-the-docs/>`_ about this topic.
103+
* Eric Holscher, one of our co-founders
104+
`talks a bit more <http://ericholscher.com/blog/2016/aug/31/funding-oss-marketing-money/>`_
105+
about funding open source this way on his blog.
106+
107+
.. _advertising FAQ: https://readthedocs.org/sustainability/advertising/faq/
108+
97109
Join us
98110
-------
99111

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ Information about development is also available:
5959
gsoc
6060
code-of-conduct
6161
ethical-advertising
62+
advertising-details
6263
sponsors
6364
open-source-philosophy
6465
story

‎media/javascript/readthedocs-analytics.js

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,5 @@
1-
// Google Analytics is a contentious issue inside Read the Docs and in our community.
2-
// Some users are very sensitive and privacy conscious to usage of GA.
3-
// Other users want their own GA tracker on their docs to see the usage their docs get.
4-
// The developers at Read the Docs understand that different users have different priorities
5-
// and we try to respect the different viewpoints as much as possible while also accomplishing
6-
// our own goals.
7-
8-
// Read the Docs largely funds our operations and development through advertising and
9-
// advertisers ask us questions that are easily answered with an analytics solution like
10-
// "how many users do you have in Switzerland browsing Python docs?". We need to be able
11-
// to easily get this data. We also use data from GA for some development decisions such
12-
// as what browsers to support (or not) or how much usage a particular page/feature gets.
13-
14-
// We have taken steps with GA to address some of the privacy issues.
15-
// Read the Docs instructs Google to anonymize IPs sent to them before they are stored (see below).
16-
17-
// We are always exploring our options with respect to analytics and if you would like
18-
// to discuss further, feel free to open an issue on github.
1+
// For more details on analytics at Read the Docs, please see:
2+
// https://docs.readthedocs.io/en/latest/advertising-details.html#analytics
193

204

215
// RTD Analytics Code

0 commit comments

Comments
 (0)