Posted in 2019

Optimizing Sphinx Documentation for Search Engines

Recently, we published a guide on SEO for technical docs with the goal of helping documentation authors and project maintainers create docs so that end users can find what they’re looking for easier.

One developer asked me point blank after I mentioned our new guide, “Hasn’t Google closed most of the loopholes that sites use to rank better?”. I’ve heard this opinion from a few technologists before so I wasn’t too surprised. Moz.com, an authority on search engine optimization, makes a distinction between what they call black hat SEO and white hat SEO to differentiate between these “loopholes” and more useful site improvements that help SEO.

Announcing API v3 Beta

In the last months, we have been working on making our API better. Considering the limitations of our current REST API v2, we decided to make a bigger step forward and create a new API v3, putting the focus on the use cases we heard about from existing users.

Compared to API v2, our new API v3 has some big differences that make it more user-friendly and useful.

GSOC 2019: Autobuild Documentation for Pull Requests

14 August 2019
Maksudul Haque
Dhaka, Bangladesh
gsoc pr-builder continuous-documentation feature

Building documentation for pull requests is one of the most requested features of Read the Docs. Similar to how a continuous integration system runs a test suite on every pull request, this change would build the documentation for each pull request and send build status notification to the providers’ Status API (e.g. Github Status API). This will let users check if the documentation build passed and also how the documentation looks before merging it to master.

As a student of Google Summer of Code (GSoC) 2019, I (Maksudul Haque) was tasked with building this feature. The main goal of my project was to make it possible to build documentation whenever a pull request was created, and send build status notification to the Providers’ Status API.

GSOC 2019: Improved Search Results and Search As You Type

13 August 2019
Vaibhav Gupta
Lucknow, India
gsoc search feature in-doc-search analytics

Giving users the ability to easily find the information that they are looking for has always been important for Read the Docs. This year, I, Vaibhav Gupta, took the opportunity provided by Google Summer of Code to improve the search. The main goals of my GSoC project were:

to make a Sphinx extension to provide “search you type” experience to the users.

Adding Custom CSS or JavaScript to Sphinx Documentation

In the Read the Docs documentation, we have a number of how-to guides to help people solve specific problems with Sphinx and Read the Docs. By far our most popular guide is on adding custom CSS and JavaScript to Sphinx.

In some older versions of Sphinx, this process was a little more challenging and it wasn’t as easy to figure out how to do it from the Sphinx docs. Sphinx 1.8 really streamlined this process especially for the simple cases.

Read the Docs Offsite 2019

The Read the Docs team just finished our first offsite ever in April of 2019. We all gathered together in person for the first time, and talked about the future of the project.

A picture will show this better than I can:

New Ad Format Coming to Read the Docs Community Sites

We view our ad program as a way to keep Read the Docs itself sustainable, and to use it to better support the community. Advertising has allowed us to have full-time employees adding new features and responding to issues in our issue tracker. We have also been able to share thousands of dollars with the open source community via our revenue share program and grants.

Currently, about 30% of our site traffic does not have any advertising. When we first launched ethical advertising in 2016, we launched only on specific documentation themes. We purposely did this slowly to make sure our ads look integrated with Read the Docs and less obtrusive to users.

Ad Funding at Read the Docs and What’s Next for Ethical Advertising

11 June 2019
David Fischer
San Diego, CA
advertising business sustainability ethical ads

It has been three years since we first launched ads on Read the Docs and while we gave a limited update in our 2018 stats, we figured it was time to give an update on ethical advertising and how it is working.

Our ethical advertising model is still going strong. We proved that it is possible to build a business model on top of advertising without resorting to user tracking. Unlike most other ad-supported sites, we show advertising based on the context of the page, not by creating behavoral profiles of large numbers of individual users. If you are browsing documentation for a Python project, you might see a relevant ad about Python. It’s that simple and it works.

New Configuration File

We are happy to announce the new version of the Read the Docs configuration file (v2).

If you are a recurrent Read the Docs user, chances are that you’ve configured your projects using a .readthedocs.yml file.

Tips for Getting a Developer Interview

Over the last month, the Read the Docs team conducted 30-40 customer development interviews with hiring managers and recruiters at companies ranging from 5-person companies to the biggest names in tech. We wanted to learn more about hiring processes at various companies with the ultimate goal of building a product to help companies find developers.

Last time, we covered some tips for hiring managers based on what companies told us they were doing. This time, we put together tips for candidates looking for their next job based on insights we heard from hiring managers.

Defaulting New Projects to Python 3

New projects that are just getting started with Read the Docs will now use Python 3 by default. While it is still possible to configure your project to use Python 2.7 with our configuration file, we think it’s important to help push the Python ecosystem towards adopting Python 3.

Our default Python version is currently Python 3.7. Projects can also select Python versions 3.6 and 3.5 using our default build image. We will eventually remove support for building projects with Python versions 3.3 and 3.4, however it is still possible to select a build image with support for either version.

Improved Search

Have you ever struggled with a poorly documented software project? What about a well documented project but you can’t find the right section inside the docs? The Read the Docs core team has realized the importance of good search for documentation and got me to take the challenge as a Google Summer of Code student. The main goal of my GSoC project was to refactor the search code together with upgrading the backend search engine, as well as adding more features to our search functionality like exact match search, case insensitive search, search as you type, suggestions and more.

Google Summer of Code is a global program where students work with an open source organization on a 3 month programming project. The core team of Read the Docs proposed some Project Ideas, one of them was Refactor & improve our search code. I (Safwan Rahman) was keen to get my hands dirty with Elasticsearch and grasped the opportunity to do so by applying for this project and I got accepted.

Lessons From and For Hiring Managers

Over the last four weeks, the Read the Docs team did dozens of customer development interviews with engineering hiring managers. We wanted to learn more about hiring processes at various companies with the ultimate goal of building a product to help companies find developers. We talked to people looking for talent at five person companies all the way up to the biggest names in tech. In this post, I am going to cover some of the common things we heard from hiring managers and share some ways for hiring managers to improve their company’s process. In our next post in this series, I will have some actionable tips for job seekers based on the same interviews.

Since this is a long post, I figured I’d share some of the key takeaways:

Incoming Webhook Deprecations

In the coming weeks and months, Read the Docs will be moving some projects away from our legacy incoming webhooks, towards our per-project webhook integrations.

Our legacy incoming webhooks were our first attempt at allowing providers like GitHub to automatically trigger builds on for projects on Read the Docs. These webhooks lacked a number of security features, and so, about two years ago, we replaced these with per-project webhook integrations instead. We added a number of features to per-project webhook integrations at the time, and we stopped new projects from using the old incoming webhooks.

Read the Docs 2018 Stats

2018 was another good year for Read the Docs. We’ve settled into a sustainability model that is working for us, and have a team of 5 folks working full-time on the project.

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