Recent posts

  • Aug 29 - 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.

  • Aug 27 - 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.

  • Aug 14 - GSOC 2019: Autobuild Documentation for Pull Requests

    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.

  • Aug 13 - GSOC 2019: Improved Search Results and Search As You Type

    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.

  • Jul 10 - 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.

  • Jun 20 - 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:

  • Jun 18 - 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.

  • Jun 11 - Ad Funding at Read the Docs and What’s Next for Ethical Advertising

    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.

  • Feb 20 - 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.

  • Feb 13 - 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.