Read the Docs Blog - Posted in 2020

Announcing Chan Zuckerberg Initiative Grant to Expand the Interoperability of Scientific Documentation

2020-11-19T00:00:00Z

We’re excited to announce that Read the Docs has received a $200,000 grant from the Chan Zuckerberg Initiative’s Essential Open Source for Science (EOSS) program. Read the Docs is the largest open source documentation hosting platform in the world. We provide hosting for many scientific software packages, including some that have received EOSS funding in the past. You can read more about this round of grants in the official announcement.

Our grant has two parts:

Part 1 allows us to develop new software to improve the interoperability of scientific documentation.
Part 2 allows us do advocacy work around the importance and value of documentation in the scientific community.

We’re excited about the chance to work with the scientific community to improve the overall experience of writing and reading documentation. We plan to do a lot of outreach to various community members, so that we can ensure we’re building tools that provide the most value. We also plan to write content that will hopefully make the process of documenting scientific code easier.

Part 1: improve the interoperability of scientific documentation

This work is something that we’ve been doing as a side project for some time now. We have an extension to Sphinx that we call sphinx-hoverxref. It provides hovering tooltips for Sphinx projects when hover over a link. You might be familiar with this functionality on GitHub or Wikipedia – this project adds that functionality to any project hosted on Read the Docs. You can see a live demo on a fork of the Python documentation.

The goal of the grant will be to expand this functionality by doing a few things:

Improving and documenting the backend Embed API on Read the Docs, allowing documentation content to be embedded anywhere on the web.
Building a JavaScript client for the Embed API, which includes tooltips showing the content on any website.
Integrating this JS client and backend API together in a new version of sphinx-hoverxref.
Extending sphinx-hoverxref to work across multiple Read the Docs sites, allowing content hovers across the entire scientific documentation ecosystem.
If time allows, also extending the backend Embed API to support Sphinx documentation hosted outside of Read the Docs, allowing even more interoperability between documentation.

We are planning to contract a frontend developer to help with this work. The Python work will likely be carried out by our existing team, funded via the grant. This is because of the complexities involved with the Read the Docs and Sphinx integration, it will be more cost effective to have people already familiar with the codebases on these tasks.

Part 2: Advocacy work around documentation in the scientific community

We know that documentation is a pain point for scientific projects. There is a lack of resources in the community, and we feel that we can be a central clearing house for better documentation tutorials and best practices. This part of the funding will be about growing appreciation and knowledge of documentation in the scientific community in general, and advocating for time to be spent on crafting good documentation with the best tooling.

Part of this work would be letting people know about the work in Part 1, promoting the tooling to make better documentation in the Scientific Python ecosystem. Beyond that, we will also promote tutorials and best practices around documentation for Scientific users, leading to more resources being available and better documentation in the community.

The high-level roadmap for this part of the grant is:

Improve documentation and promote the work in Part 1.
Adapt the Guides section of the Read the Docs documentation into a more full-featured Education section, along with standardizing and editing all existing guides.
Expand our existing Sphinx Tutorial, hopefully adding it upstream to Sphinx as the official tutorial
Write additional documentation guides focused on the scientific community, based on feedback from people in the community. This will likely include tutorials on integrating Jupyter with Sphinx, Jupyterbook, and other pain points that users have.
If time allows, we would also love to work on curating some of the documentation resources at Write the Docs, specifically topics that are relevant to scientific projects.

As part of this work, we plan to contract someone in a technical writer/developer evangelist role. Someone with knowledge of the scientific community would be a great benefit, given that we plan to seek feedback from many scientific projects on the priority of tasks we work on.

Looking forward

We are starting to look for contractors who would be a good fit for the work. People who care about documentation and are already connected with the scientific community are a big plus. We hope to post proper job descriptions for these roles in the near future, but wanted to note that we’re looking in our initial announcement.

This is the largest grant that we’ve ever received, and we are working hard to make sure it’s successful. We appreciate the trust that the Chan Zuckerberg Initiative has placed in us, and we will work hard to make sure the results of this grant will be adopted across the scientific ecosystem.

If you want to keep up to date with this work, you can follow along on GitHub or subscribe to our blog for updates.

Advertising update and open sourcing our ad server

2020-07-01T00:00:00Z

It’s been a while since our last advertising update and it felt like a good time to talk about what’s working with our advertising model and how things are getting better.

How advertising is working for Read the Docs

In our 2019 stats post, we broke out our advertising revenue which was fairly flat year over year. The way our ad business is structured, our revenue mostly grows with increases in traffic and Read the Docs is mature enough that it isn’t doubling in size every year.

With that said, we’re pleased with our steady and sustainable growth. Read the Docs doesn’t have any investors putting pressure on us for short term growth and that has allowed us to invest in our ad business, commercial hosting, and in our community version for the long term. We’ve rolled out a huge number of improvements to all the sides of our business in the last year and we’re happy with the results. Advertising remains the single largest source of funding for Read the Docs and one that scales as our costs scale.

On a real world note, Covid-19 had a short term impact on our advertising revenue with a number of advertisers understandably pulling back due to uncertainty in funding and the economy in general. While the world isn’t completely back to normal, we have returned some degree of normalcy and most of these advertisers returned once there was a bit more clarity in the broader economy and the virus’ effect on the tech industry specifically. Advertising on Read the Docs is now close to capacity in the US, Canada, and Europe which are our largest advertising markets.

Improved targeting for ads

Advertising on Read the Docs is different from most ad networks out there. Our ad targeting is based on the content and the reader’s geography rather than personal data about our users. Read the Docs’ authors and readers have told us that privacy is important to them. That’s great because it’s important to us too! With that said, there are great ways to target specific content niches with ads relevant to those readers without compromising on privacy.

To start, we chose a few groups of content advertisers can target where we have enough traffic without the ads being focused on a tiny number of projects. These niches are:

Data science and machine learning
Frontend web development
Backend web development
Security
DevOps
Technical writing

We tested this improved content targeting with a select group of advertisers and the results were great. In some cases we saw click through rates more than double. Whether the ad is to hire a developer or to promote a service, we always want to deliver ads that are most relevant to the documentation being served. This results in better value to our advertisers while still respecting the privacy of our readers.

Would your company like to get in front of more developers?

Tell your marketing or recruiting team about Read the Docs and show them how they can reach over 7 million developers who Read the Docs each month!

Open sourcing our ad server

One thing we’ve wanted to do for a long time is open source the code we use to run advertising at Read the Docs. While there’s always a bit of an incentive to keep advertising code closed so it can’t be abused, our hope is that the trust we’re building with the ethical ads model can be used by others who want to run their own ethical advertising. Read the Docs is an open source company and it’s nice to have all our code out there. We call it the ethical ad server.

The ethical ad server is built to handle the kind of load Read the Docs itself receives – over a million hits per day – and it delivers advertising based only on content and geographic targeting rather than building up user profiles from personal information. It’s built from the ground up with user privacy in mind. We’re excited to share it with you so please check out the code on GitHub.

Conclusion

Just as we’re constantly delivering improvements to Read the Docs itself for our readers and project maintainers, we also strive to give a better experience and better results to the companies who trust Read the Docs as a marketing channel. I want to thank all our advertisers who believe in our approach and continue to support us and stay tuned to this space for more great features in the future!

Our ethical ad network is just about ready for launch and we’re actively looking for projects to beta test the network. If you run a developer focused website and you’re looking for a way to earn money without selling out your visitors’ privacy, please get in touch.

Shipping a CDN on Read the Docs Community

2020-05-18T00:00:00Z

You might have noticed that our Read the Docs Community site has gotten faster in the past few weeks. How much faster likely depends on how far away you live from Virginia, which is where our servers have traditionally lived.

We have recently enabled a CDN on all Read the Docs Community sites, generously sponsored by CloudFlare. This post will talk a bit more about how we implemented this, and why we’re excited about it.

We are also offering the CDN option to our Read the Docs for Business users on the Enterprise plan, you can reach out to us if you’re interested.

Hosting thousands of domains is hard

Traditionally the largest problem that we’ve had with rolling out features to all of our documentation sites is scale. We host thousands of custom domains for our users, and any solution needs to work across all of them. This has presented a number of issues in the past, but CDN is one of the most complicated.

To make a CDN function across all our sites, every data center that the CDN has needs to work with all our custom domains. Imagine we have 5,000 domains and there are 100 data centers across the world, this means that 5,000 * 100 = 500,000 different endpoints need to be configured for this to work at scale.

We are lucky that CloudFlare has the global scale to be able to donate us this service. Specifically, their SSL for SAAS service is what we’re using for both SSL and CDN across all our custom domains. This allows us to offload the complexity to CloudFlare, and only focus on our integration.

Implementation

One of the coolest things that CloudFlare’s CDN offers is something called Cache Tags. This lets us add a Cache-Tag header to all the documentation that we serve, and invalidate the cache using just that tag.

An example, when you load our docs, we will return a header:

GET https://docs.readthedocs.io/en/latest/
...
Cache-Tag: docs,docs-latest

We return a tag that matches both the $project, and the $project-$version. This allows us to invalidate the cache for a specific version, or across the entire project.

As you know, cache invalidation is one of the harder problems, so we take a pretty conservative approach. We invalidate the cache in the following scenarios:

Project cache on Project or Domain save
Version cache on documentation builds for specific versions

The client code is quite simple, a single HTTP request to Cloudflare’s API with a list of tags to clear.

Outcomes

There are two important outcomes from this work:

Page loads are much faster for users around the world
Our server load has gone down quite a lot because we handle fewer requests

The biggest winner here is our users. Docs are faster for everyone, and we are looking at implementing additional features into our documentation hosting code now that we have reduced load.

We hope that Read the Docs Community has gotten noticeably faster, and that in the near future it will continue to get better with the new features that this enables.

Read the Docs 2019 Stats

2020-05-14T00:00:00Z

2019 was another good year for Read the Docs. We continue to have a team of 5 folks working on the project, and we’ve rolled out a number of new features for the year.

Here are our stats for the past year, which we’ve published since 2013. This is part of our effort to be transparent in our organization, as well as our source code.

Note

You can always see our stats for the last 30 days.

Our posts from 2013, 2014, 2015, 2016, 2017, and 2018 are also available.

Page Views

Our stats:

465 Million Page Views (from 400M)
120 Million Unique Visitors (from 77M)

These numbers are not completely accurate, since we implemented Do Not Track support last year, our analytics pageview figures understate our actual traffic. We estimate that around 6% of users are not counted here. We also don’t count all the users who block Google Analytics with a browser extension.

Site Stats

The stats, in total numbers:

200,000 projects (from 100k)
400,000 users (from 150k)
10,188,182 builds (new this year)

We have been battling spam quite heavily again this year, so these numbers are a bit skewed. We do notice a uptick in usage across the site, both in terms of support and traffic.

Community

This year, we had:

21 people who committed code to the main repository (from 28)
4793 commits (from 3774)
609 issues - 80 open, 529 closed (from 797)

We have continued to have a similar team working on the project this year, but have actually made more commits. We moved our support queue from issues to email, which likely accounts for the lower issue count. We’re quite happy with our closed issue stats this year, which are much better than previous years.

Funding

$275,000 in revenue from readthedocs.org (from 294,000)
$249,000 from advertising (from $278,000)
$26,600 from Gold users (from $16,000)
We have additional revenue from our commercial offering at readthedocs.com, but aren’t including that in our community funding overview

Our advertising has been pretty steady for 2019. The small drop in the year-over-year comparison we account to the fact that ad blockers happened halfway through 2018, meaning that the comparison is 15% lower in terms of our total traffic.

We continue to be hosted by Azure, and we’re using a lot of their nicer feature to keep our costs down. You can find some posts on our blog about this.

Conclusion

We continue to keep working to improve the documentation ecosystem in the software industry. We’re excited about a number of new features that we’re working on this year, and expect to continue to be a resource you can depend on for a long time to come :)

Automation Rules

2020-05-04T00:00:00Z

A time ago we introduced a new feature to help users to automate some tasks on Read the Docs. Automation rules.

If you manage a project with several versions, you may have noticed that Read the Docs doesn’t always activate your new versions [1]. If you require to do any action over a new version, you’ll need to log in your Read the Docs account and manually do so.

With automation rules, you can choose what do to after a new version is created. To add a rule, you only need to choose a pattern and an action. After that, every new tag or branch that matches the pattern will trigger the action.

Currently, we only have two actions available:

Activate version
Set version as default

For the pattern, you can select:

All versions
The ones that match SemVer
Or you can write your own using a regular expression

With automation rules you can do things like:

Activate new tags only
Activate only branches that start with v
Activate tags and branches that belong to the 1.x release
Set as default tags that have the -stable or -release suffix
Activate all tags except those containing the --nightly suffix

Find more information and examples in our documentation.

What other tasks you would like to automate? Let us know on a GitHub issue!

[1]	We activate and build new versions automatically only if you follow PEP 440, and the new version is greater than the current stable version.

Better support for scientific project documentation

2020-04-28T00:00:00Z

In the past year, we’ve been having issues when building projects’ documentation using conda. Our build servers were running out of memory and failing projects’ builds. Read the Docs has this memory constraint to avoid misuse of the platform, causing a poor experience for other users.

Our first solution was a dedicated server for these kind of projects. We would manually assign them to this server on user requests. This workaround worked okay, but it involves a bad experience for the user and also us doing a manual step each time. Over time, we hit again the same issue of OOM, even giving all the memory available to one project to build its documentation. After some research, we found that this is a known issue in the conda community and there are some different attempts to fix it (like mamba). Unfortunately, none of them became the standard yet and the problem is still there.

Meanwhile, in another completely different set of work, we were migrating all of our infrastructure to a different architecture:

Azure Virtual machine scale sets for autoscaling our servers,
Azure storage accounts to store all the user’s documentation
Proxito, an internal service to remove a lot of the state from our servers (more about this migration coming in a future post)

This helped us to reduce costs and allowed us to spin up bigger instances for the builders. We have also made some other important operational changes:

Our builders are now single-process, giving all the memory available to only one project without worrying about affecting others.
We added custom task router that routes small builds to small servers (3GB RAM), and big builds to larger servers (7GB RAM). This removes the need for users to ask us to upgrade their isntances.
Assigned all conda projects to be built by big servers by default.

If you ever had a memory issue on Read the Docs, we’d appreciate if you give it a try again. Please let us know about your experience when building scientific documentation. If you know that any of your friends were hitting this issue in the past, we encourage you to talk to them and tell them to give it a try.

We are excited to have more scientific documentation on our platform and we are doing our small part to make this happen and have better science in the world.