Read the Docs Blog - Posted in 2018

Tips to Hire Developers with Read the Docs

2018-10-30T00:00:00Z

Read the Docs is probably not the first place you think of if you are recruiting. However, over 7 million unique developers use Read the Docs each month from all over the world. We didn’t set out to build a better job board, but after a number of advertisers used our ethical ads for recruiting, we discovered that Read the Docs was a great place to find developer talent.

Hiring with Read the Docs works

Developers are not always actively job seeking by browsing job boards or company careers pages. However, they are on Read the Docs reading about the libraries and frameworks they use. Even when people aren’t actively looking for a new job, many are open to exploring new opportunities.

On Read the Docs, we found that developers engage with hiring ads at a higher rate than any other kind of advertising. With hiring ads, developers get ads that are relevant and interesting and companies reach the folks actively using the tech they are recruiting for.

Be specific and find the right developers

If you are looking for Python developers, you can configure your hiring ad to only show on Python related documentation. You can further refine your audience to Read the Docs visitors in specific regions. Whether you are looking for a remote Python data scientist or a blockchain developer in Switzerland, be as specific as possible. This ensures you don’t get unqualified candidates as well as making sure you catch the eyes of the people you are interested in.

Set the right expectations

In any type of advertising, setting appropriate expectations can make the difference between a lackluster and successful campaign. In hiring, it is even more critical. This means making sure that your hiring ad for a front-end JavaScript developer links directly to your JavaScript developer job listing page where people can click “apply”. Don’t link to a listing of all of your open positions unless your hiring ad sets that expectation. Nothing is worse for the developer than clicking on a hiring ad and not knowing what to do next.

Likewise, some things can set the wrong kind of expectation. Most developers have seen enough hiring posts for “rockstars” and “ninjas” to know what to expect. Be honest and upfront and you will attract the right folks.

Stand out

Developers get contacted all the time by recruiters and it can be difficult to show prospective employees why they should check out your company. People look for all sorts of different things when seeking a new job from working with a high-caliber team to working for a company whose goals they agree with. You should highlight your best selling points right on your hiring ad as early as possible. If your company affords a fantastic work/life balance, mention that. A company in a great location, with a beautiful office, and top of the line hardware should definitely feature that. Focusing on your best attributes shows you care about your developers and helps you appeal to people who care about your products and mission.

Are you hiring?

Find qualified candidates already using your tech by promoting your job openings with Read the Docs.

Community Advertising

2018-09-06T00:00:00Z

As part of our ethical advertising model, Read the Docs gives away 10% of our ad inventory to projects, conferences, and other initiatives in the open source community. Many of these projects operate as Read the Docs did in the past with little to no income. These are not groups that traditionally have the resources to use paid advertising.

We have run ads for:

Various Python conferences from PyCon to smaller regional conferences
Many topic or framework specific conferences such as Djangocon US and Sustain
Python Software Foundation
Mozilla
Beeware - tools and libraries for building native apps in Python
Godot - an open source game engine
Kiwi TCMS - an open source test case management system
World Possible - an education non-profit
Write the Docs - a series of events for documentatarians

Get in touch. We can help!

If you run a conference, non-profit, or a funding strapped open source project, we would love to help you get the word out. Make sure you qualify for our community ads and send us an email to be considered for the program.

If you have any feedback about our community advertising program, we’d love to hear from you too.

HTTPS for Custom Domains

2018-08-13T00:00:00Z

Read the Docs hosts documentation for over 80,000 open source projects and over 2,500 of those projects are hosted on their own individual domains. Documentation hosted on *.readthedocs.io has supported HTTPS for a number of years, but one of our most requested features was to make HTTPS on other domains easy. Today we are happy to announce that Read the Docs supports HTTPS on custom domains!

Earlier this year, Cloudflare contacted us to support HTTPS for the thousands of open source documentation projects on their own domains. They generously provided us with their SSL for SaaS package to ease the integration on our side.

Why HTTPS is important

HTTPS encrypts traffic between your computer and Read the Docs’ servers and allows your browser to verify that the website you are talking to is the one that you requested. HTTPS ensures there is no man-in-the-middle snooping on your connection.

Configuring your domain

If you followed our documentation for custom domains and you are using a CNAME to point to Read the Docs, no action is required on your part.

If you have had your Read the Docs setup for many years you may have followed some old directions that suggested creating a CNAME to readthedocs.org or <slug>.readthedocs.org. Depending on your setup, we may not have been able to issue a certificate for your domain. In that case, update your CNAME to point to readthedocs.io.

Why did it take so long?

It’s 2018! HTTPS is supposed to be easy, right? For a few domains, getting a certificate isn’t too hard. For 2,500+ domains, things get a bit more complicated.

We identified a number of challenges including:

Retrying failed requests to issue certificates
Handling when users remove DNS records that would allow us to issue certificates
Getting our web servers and load balancers to handle dynamically adding and updating certificates on the fly
Handling recurring tasks to re-issue updated certificates before they expire

Cloudflare reduced most of this complexity to a few API calls made when a new domain is configured or removed. Without their support, we would still be working on this feature.

Next steps

There are a few more things left on our road map for this feature. In the next few weeks we will begin to generate HTTPS links for custom domains where we have a certificate. After that change has been deployed for a few weeks, we will begin to redirect custom domain traffic to HTTPS.

As always, if you’re having any trouble with a particular domain, don’t hesitate to let us know in our issue tracker.

Planned Move to Azure

2018-08-09T00:00:00Z

We wanted to make you aware that on Saturday August 18 at 10:00am PDT (1:00pm EDT, 17:00 UTC), Read the Docs will be having a scheduled downtime of approximately 4 hours.

To ensure the stability and performance of our system, we are performing this upgrade during the weekend which is our period of lowest usage.

During this maintenance window, documentation will still be serving but new documentation builds will not trigger and the Read the Docs dashboard will not be available. New builds and webhooks will begin processing once the maintenance is over.

We are moving our service to our new home on Microsoft Azure who have generously provided us with credits to support open source software. Some of the features we are most excited to take advantage of with this move are managed services for Postgres and Redis as well as improvements to file storage. This should simplify our operations considerably.

We’d like to thank Rackspace for sponsoring our hosting for over 4 years. They were a large supporter of open source, and Read the Docs wouldn’t be what it is today without them.

Thanks to everyone for your support and understanding!

Read the Docs Public API

2018-08-02T00:00:00Z

Recently, we revamped Read the Docs’ public API. Previously, our latest API (v2) was used by our build processes but not heavily used by outside users.

As part of this process, we put effort into making sure the API is easy to use to access Read the Docs projects, builds, and versions, easier to filter builds and versions by a particular project, and that the documentation is up-to-date.

Deprecation of API v1 and connecting over insecure HTTP

As part of this process, we are formally deprecating support for our API v1. It will be supported through at least January 1, 2019 but we strongly encourage all users to migrate to API v2 at their earliest convenience.

In addition, both API v1 and API v2 allowed connecting over insecure HTTP as opposed to HTTPS. Beginning in January 2019, we will be redirecting requests over HTTP to HTTPS. This will improve security and allow us to add more security related features to the API going forward. For most users, this should be a one line change to connect to the HTTPS version of the API.

Get in touch

We are always interested in the amazing things people create when data is openly shared. In addition, we are always looking in improve our API to enable more projects and mashups. If you use Read the Docs’ public API for your project or there are additional features you’d like to see in it, we would love to hear from you.

Do Not Track at Read the Docs

2018-06-08T00:00:00Z

Today, we are pleased to announce that Read the Docs honors Do Not Track (DNT). DNT is a browser preference that requests that a user not be tracked across the internet while browsing the web.

While there isn’t a consensus on precisely what DNT should mean, we are following the Electronic Frontier Foundation’s (EFF) guidelines for Do Not Track as we believe that gives a good balance between the privacy expectations of users and the reality of running a business and keeping Read the Docs sustainable.

What we implemented

Not much needed to change to make Read the Docs support DNT and many of these changes were already necessary for the EU’s new privacy regulation.

Here’s a brief list of what we did for Do Not Track:

Our logs that store any personal data are deleted after no more than ten days. We do this for all users even those who don’t have DNT enabled.
When a user has DNT enabled, we do not send data to our analytics. Based on our initial data, this looks like about a 6% reduction.
While this didn’t change, we reiterated that we do not do behavioral ad targeting regardless of DNT preference.

Full details on Do Not Track at Read the Docs can be found in our privacy policy.

What DNT means for our advertising

Advertising at Read the Docs was already built with privacy in mind. With our Ethical Ads, we previously committed to not tracking users, not selling user data, and hosting ads ourselves which all align perfectly with Do Not Track.

Our support for DNT formalizes our commitment to the high standards for privacy produced by the EFF. It also make us one of very few ad networks that honor Do Not Track.

The Ethical Ad Network

In a previous post, we mentioned that we are taking the same developer-centric, privacy-focused advertising we have on Read the Docs and expanding this to a larger ad network for open source infrastructure.

Supporting Do Not Track is an important milestone along the way as it confirms our commitment to privacy in advertising. We believe that ads don’t have to track people to be effective.

Our Ethical Ad network is still in its early stages, but if you want to know more or you know a project that could use it, please get in touch.

GDPR: What it means for Read the Docs

2018-05-25T00:00:00Z

Update on Ad Blocking and Acceptable Ads

2018-05-21T00:00:00Z

A few weeks ago, we shared about the challenge ad blocking presented to our sustainability and what we were doing about it. On May 4th, Read the Docs was added to the Acceptable Ads list meaning that our visitors running ad blockers who choose to allow unintrusive advertising will see our ads again. The impact to our ad views, clicks, and revenue was immediate.

Data on our inclusion in the Acceptable Ads list

32% of Read the Docs visitors run an ad blocker

Estimates around the web vary regarding what percentage of people run ad blockers and it varies heavily by industry. We discussed this figure a bit in our previous post.

It took a month from application to inclusion in the list

We discovered about our inclusion in the EasyList ad blocker list within a couple days and immediately applied to the Acceptable Ads program. No changes were required of us to meet the Acceptable Ads criteria and we also qualified for Acceptable Ads without third-party tracking.

While Eyeo, the company behind AdBlock Plus, derives most of their revenue from the Acceptable Ads initiative by charging large entities, Read the Docs did not pay for inclusion on the list.

Over half of those running an ad blocker allow acceptable ads

Given our more tech-savvy and privacy-focused audience, we didn’t know what to expect. Not every ad blocker allows acceptable ads by default and even then users can choose to turn them off.

People running ad blockers DO click on ads

We can definitively say this is true of our audience. Our click-through rate did not change based on ad blocking or our inclusion in the acceptable ads list at all.

Of the ad views and clicks blocked by ad blockers, inclusion in the Acceptable Ads list meant that 55-60% of our ad-blocking visitors choose to allow our ads. This directly translated into revenue toward our sustainability.

Building our Ethical Ads

The Acceptable Ads list is definitely a step in the right direction for us. We share the goal of unintrusive advertising that respects our audience.

People understand that advertising funds much of the web. As ads got larger, more annoying, and ad networks stored more information on millions of people, however, many people finally decided to install ad blockers. This is the largest boycott in human history and blaming users isn’t the answer.

Based on our experience with ad blocking and the Acceptable Ads list, it is clear that visitors will allow advertising that doesn’t disrupt user experience and doesn’t track people.

We are glad to have made progress toward regaining our sustaining revenue. Read the Docs is continuing on our experiment to fund open source infrastructure in a way that is a win/win for all parties, and we are glad you’re following along with us.

Social Version Control Log in

2018-05-17T00:00:00Z

Ads and Ad blockers

2018-05-02T00:00:00Z

Last time, we shared how ethical advertising works to keep Read the Docs sustainable without creepy ad targeting. This time, we will share about one of our biggest challenges with advertising. At the beginning of April, Read the Docs was added to one of the most popular ad block lists: the Easylist.

Ad blocker fallout

Getting added to the EasyList had a significant and immediate impact on the bottom line at Read the Docs. Right around April 1, 32% of our ad views simply vanished. At first, we thought we had done something horribly wrong but then we discovered that this was due entirely to ad blocking. Our actual traffic wasn’t down at all.

Users’ browsers were simply downloading the updated EasyList which blocked ads on Read the Docs. In terms of ad viewership, weekdays – our busiest days and the peaks in the graph – became more like weekends and weekends fell off a cliff. We had always guessed what percentage of our user base ran ad blockers. Now we know. We knew this day would come as we became more successful but we had hoped it was a ways off considering we weren’t part of a large ad network.

This directly affected our operations and staff. Our operating costs didn’t go down in any significant way, but revenue sure did. Advertising is by far the largest source of revenue at Read the Docs and it just dropped by about a third. This meant that we had to cut some costs where we could and slow down some hiring plans. While Read the Docs is not a non-profit company, all the revenue is reinvested into the project itself, paying maintainers, and other places in the open source ecosystem. The situation is not dire by any means, but it was certainly disappointing that we ended up on the same list with popup advertisers who couldn’t care less about privacy.

All about ad blockers

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 ad network we wanted to exist with only relevant ads and no creepy behavioral targeting.

According to a 2017 report from PageFair (pdf), a company that specializes in quantifying ad blocking, 11% of global web users run an ad blocker. Considering that Read the Docs’ core audience is tech-savvy, privacy-conscious developers, it should be no surprise that our number is higher.

What are we doing about it

It will be an uphill battle to get back to where we were in terms of revenue and sustaining Read the Docs, here are a few things we are working on:

We applied to the acceptable ads list, an ad block list enabled on many ad blockers by default that enables some unobtrusive advertising. We are very hopeful here but it does take quite a bit longer to get on this list than it does to get blocked.
Nagging users into allowing ads on Read the Docs. We are envisioning more of a polite nag in a similar vein to jsfiddle rather than an “adblock wall” which prevents usage of Read the Docs until it’s allowed.
Blogging and raising awareness of how ad blocking affects us and other open source projects.

While we could simply change our CSS and ad API to avoid blocking since we host our ads ourselves, we decided not to engage in a cat and mouse game since this work would not benefit users.

Advertising funds much of the web and many people recognize that while there are plenty of bad actors in the ad industry – think pop-under ad networks or ads that navigate your browser for you – some advertising is necessary to power the web we know and love especially when it comes to open source software which has unique funding challenges.

Update: On May 4th, Read the Docs was added to the acceptable ads list! We will collect data over the next couple weeks and have a follow-up post on what effects this had on advertising.

Open source advertising list

At Read the Docs, we also discovered that we are not the only open source project that got our advertising blocked by ad blockers. Many open source projects that fund themselves through advertising get blocked and some of them don’t have the resources to navigate the acceptable ads program or understand the inner workings of ad blockers.

Likewise, some web users may not want to allow all acceptable ads which includes many ads from the big networks but we are hoping they would be willing to accept ads that benefit their community of software developers.

We are launching a new initiative to allow advertising that benefits open source software. We encourage you to subscribe to the this list and support open source. If you run an open source project affected by ad blockers, we would love to help you too.

Advertisers

If you are an advertiser interested in reaching a 100% developer audience who cares deeply about privacy, we would love to hear from you too.

Read the Docs Blog - Posted in 2018

Tips to Hire Developers with Read the Docs

Hiring with Read the Docs works

Be specific and find the right developers

Set the right expectations

Stand out

Community Advertising

Get in touch. We can help!

HTTPS for Custom Domains

Why HTTPS is important

Configuring your domain

Why did it take so long?

Next steps

Planned Move to Azure

Read the Docs Public API

Deprecation of API v1 and connecting over insecure HTTP

Get in touch

Do Not Track at Read the Docs

What we implemented

What DNT means for our advertising

The Ethical Ad Network

GDPR: What it means for Read the Docs

What changed at Read the Docs

Ethical Ads

Update on Ad Blocking and Acceptable Ads

Data on our inclusion in the Acceptable Ads list

Building our Ethical Ads

Social Version Control Log in

For new Read the Docs users

For existing Read the Docs users

Ads and Ad blockers

Ad blocker fallout

All about ad blockers

What are we doing about it

Open source advertising list