Read the Docs Blog - Posted in 2019

Optimizing Sphinx Documentation for Search Engines

2019-08-29T00:00:00Z

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.

Black hat SEO is basically a set of tactics some sites use to improve rankings without actually making their site better to end visitors. This includes techniques like displaying different content to search engines (cloaking), link farming, or adding semi-relevant keywords into a page (keyword stuffing). When Google and Bing discover a site doing this, they take action and lower a site’s ranking until the problems are fixed. Black hat SEO is inherently risky and we try to stay away from this kind of SEO.

Instead our guide focuses on white hat SEO which aims to improve your docs’ search engine rankings by helping search engine’s understand and index your docs better and present it better to searchers. This kind of SEO isn’t trying to cheat search engine rankings and it’s a win for everyone. Searchers find the content they’re looking for more easily while search engines understand the content better and can show more relevant results.

Specifically, we also tried to focus on SEO for documentation and how Sphinx and Read the Docs make it easier including:

Making your docs display better on search engine results
Helping search engines understand and index your docs better
Improving your ranking based on user and search engine feedback

Making your docs display better in search results

Google search engine results with the page title, URL, and a description.

Displaying more relevant information in search results will cause more people to click through to your docs. Again, your goal is not to use cheap tactics to rank better and trick users into clicking. Rather, you are trying to legitimately improve your content such that users better understand what to expect on a page before they click.

Some of the most important aspects of improved search listings are:

Use descriptive and accurate titles in the HTML <title> tag. With Sphinx, the <title> comes from the top heading on the page.
Ensure your URLs are descriptive. They are displayed in search results. For Sphinx, the URL uses the source file’s filename.
Make sure the words your readers would search for to find your site are actually included on your pages. Ideally, these key words should be in your <title> or description.

These concepts are not only important in helping guide users to click on your documentation, most of the same optimizations are useful to the search engine when indexing your site and when ranking your site for searchers.

Helping search engines understand your docs

Search engines like Google and Bing crawl through the internet following links and redirects in an attempt to understand and build an index of what various pages and sites are about.

These tips and features can help you control how search engines index your docs:

Make sure your entire site can be navigated by following links. If you have “orphan” pages, a search engine won’t find them. Using Sphinx’s “toctree” directive helps make sure all your pages are indexed and navigable.
Redirects and canonical URLs are useful when the same content exists in multiple places or moves from one page to another. Read the Docs dashboard lets authors setup redirects from one page to another or from one version of the documentation to another.
Using a robots.txt and sitemap.xml file can help you control how search engines crawl your docs. For example, you could tell search engines to ignore unsupported versions of your documentation. Read the Docs provides both a robots.txt and a sitemap and has ways for you to override them.

Improving your SEO ranking from feedback

Search engines provide tools to help webmasters build their site better and to give insights and feedback about the indexing of sites by the search engine spiders. Google Search Console and Bing Webmaster Tools are tools for webmasters to get feedback about the crawling of their sites (or docs in our case). These tools can show technical issues with indexing like pages that are failing for some reason and also possible security or spam issues on your site that can lower your ranking.

Google search console showing an issue with user generated spam, a constant battle at Read the Docs.

Feedback on keywords users use to find your docs is also really helpful. This is true both for the phrases people searched for on a search engine and for the search terms people queried in Sphinx and Read the Docs’ built-in search features. Analytics tools like Google Analytics can provide these insights, but as part of our search improvements and search analytics, Read the Docs is going to show project maintainers the most common search queries to help them improve as well.

SEO is no substitute for good writing

One area we didn’t detail in our guide is how more general improvements to technical writing can also improve your search engine rankings. This could be a whole post by itself.

Using simpler words, for example, has a number of advantages in technical writing. The excellent Microsoft Style Guide recommends using simple words and concise sentences and Apple’s Style Guide echoes the same sentiment. Simpler sentences are easier to understand for both people as well as machines like search engines and automatic translators.

While any style guide you read will tell you to avoid using jargon, technical writing and software docs have a certain amount of unavoidable technical terminology. Defining these terms and phrases when you first use them helps users as well as search engines.

In summary

Always keep in mind that your ultimate goal is to make your docs more discoverable by people, not machines. While the concepts and tactics here will help you rank better with search engines, providing high quality documentation and making it easier to find and understand is the best way to make sure people actually read the docs.

Announcing API v3 Beta

2019-08-27T00:00:00Z

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.

These differences includes:

API access requires authentication
Token based API authentication
Read and write
Resource lookup can use project’s slug
Wider resource coverage

Some examples of new queries and actions that will be possible with the API are:

If you want to know more about it, please check out the full APIv3 documentation.

Invite-only beta feature

APIv3 is currently in an invite-only beta state on our community site, https://readthedocs.org. In case you want to test it and give us feedback on it, please email us to get early access.

Based on the feedback we receive from you, we plan to add more features to cover most of the common use cases. Please, help us with your feedback to make the new APIv3 even better!

GSOC 2019: Autobuild Documentation for Pull Requests

2019-08-14T00:00:00Z

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.

To see this feature in action you can click on one of the pull requests on readthedocs.org repository.

GitHub Build Status Reporting for Pull Requests

Google Summer of Code

Google Summer of Code is a global program where students work with an open source organization on a 3 month programming project. Autobuild Documentation for Pull Requests was one of the project ideas on Read the Docs Project Ideas for Google Summer of Code 2019. I applied for the project and got accepted.

I started working on this project since May 2019. All of my work on this project can be seen in the Pull Request Builder Board.

Background

Many of our users wanted a way to visualize the documentation update that was made in a pull request. They also want to know whether the documentation build will pass before merging the pull request to master. This would allow users to have more confidence on the pull request and make the pull request less likely to break the documentation after merging. So, to achieve this Read the Docs core team selected Autobuild Documentation for Pull Requests as one of the projects of Google Summer of Code 2019.

Pull Request Builder Features

Currently I have implemented these features and working on more upcoming features. Some of the major features are as follows:

Creating External Versions: We create an external version when we receive a pull request webhook event for a project from GitHub and trigger a build for that version. External versions are short-lived versions that are separate from the project’s main documentation.
Synchronizing External Versions: Whenever there is a new commit on the pull request, we synchronize the external version for that pull request and trigger a new documentation build with the latest changes.
Deleting External Versions: Whenever the pull request is closed or merged, we delete the external Version associated with that pull request.
Warning Banner for pull request documentation: While building documentation for pull requests we add a warning banner at the top of those documentations to let the users know that this documentation was generated for pull requests and is not the main documentation for the project.

We send build status reports to the status API of the provider (e.g. GitHub). When a build is triggered for a pull request we send build pending notification with the build URL and after the build has finished we send success notification if the build succeeded without any error or failure notification if the build failed. By going to the build URL provided in the status report users can view the build steps and also see the documentation generated by that build.

Currently, we only support GitHub and planning to extend to GitLab and BitBucket.

Getting Started

Building documentation for pull requests is currently in Beta testing and only supports Github repositories. If you want to dive in and enable this feature for your project you can email us with the URL of your ReadtheDocs project.

Future Improvements

We are planing to extend this feature to other platforms such as GitLab and BitBucket. We are also planning to make this feature more customizable through our configuration file (.readthedocs.yaml). If you have any improvements or features in mind for building documentation for Pull requests we would love to know about it. Please feel free to let us know by submitting an issue on GitHub.

Contributors Wanted

As Read the Docs is an open source project backed by a small team of developers, most of them are busy to keep things up and running only. Therefore, its quite hard for them to take time to implement new features. We would like to get more contributors to improve this feature. If you know a bit of Django and Python and interested to improve this feature you are always welcome to contribute. If you need any support to start contributing, you can get in touch with me or any other member of Read the Docs team. You can find all of us at #readthedocs freenode IRC channel or readthedocs gitter channel. I am saadmk11 at IRC and @saadmk11 at gitter.

Conclusion

To conclude, I would like to say this was a much needed feature for Read the Docs and also its users. This feature will improve our platform and make it a true Continuous Documentation platform. I think that many users will benefit from this feature. We will keep making improvements along the way for a better user experience.

GSOC 2019: Improved Search Results and Search As You Type

2019-08-13T00:00:00Z

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.
to add support for multiple hits per search result.
to improve the UI/UX around code search.
to add support for search analytics.

Search as you type feature is live on our docs. You can go through these links to experience it:

Google Summer of Code

Google Summer of Code is a global program where students work with an open source organization on a 3-month programming project. I got accepted in the program and was excited to spend my summer with Read the Docs.

I have worked full time during the GSoC coding period and implemented various features. All of my search related work can be seen in the In-Doc Search UI Project Board.

Background

The search code was originally contributed by Rob Hudson, back in 2013 and then improved upon by other contributors. It was greatly improved and upgraded by Safwan Rahman during GSoC’18. Continuing on the same path, I have implemented some new features on top of the existing search backend.

New Features

During the GSoC period, I have worked on the following features:

In-Doc Search UI: readthedocs-sphinx-search is a sphinx extension that adds a clean and minimal search UI to your docs. It supports “search as you type” feature. So, it is now possible to get instant results without being redirected to any other page. Read the docs here.

In-Doc Search UI Demo

Multiple Hits Per Search Result: This is one of the highly requested features. We now support search results from the sections of the docs, clicking on which will take you to that particular section and not just to the top of the result page.
Code Search: We now support code search. If you want to search a particular function or an API endpoint – you can just type your query and you will find it in the results. Eg: api/v3/ or module.function.
Search Analytics: We now have support for search analytics. These analytics makes it easy to know what the users are looking for in your documentation. You can see these analytics in your project admin dashboard. Currently, this feature is in beta state and is available under a feature flag. We plan to make this available for everyone soon. If you want to test this feature out and help giving us feedback, please contact us via GitHub issues.

Search analytics demo dashboard

What Next?

We don’t intend to stop just yet. We are planning to work on some more cool features in the near future, some of which are:

Search Facets: Facets can be used to make search more accurate. For example: In Celery docs, facets can be used to search inside Kombu docs for “serializers”, like subproject: kombu serializers. (readthedocs/readthedocs.org#5966)
Search Results Ordered By Most Viewed Pages: It would be much more useful if the most viewed pages are shown first in the search results. (readthedocs/readthedocs.org#5968)
Search Inside Sections: It would be good if users have the option to get the search results from a particular section of the documentation. For example: Getting results from only Guides of our documentation. (readthedocs/readthedocs-sphinx-search#23).

Contributors Wanted

As Read the Docs is an open source project backed by a small team of developers, most of them are busy just keeping the site up and running. Therefore, it’s quite hard for them to take time to implement new features. If you know some bit of Django or Python and Elasticsearch, you can contribute to the search functionality of Read the Docs. If you need any support to start contributing, you can get in touch with me or any member of Read the Docs team. You can find all of us at #readthedocs freenode IRC channel or readthedocs gitter channel. I am dojutsu-user at IRC and @dojutsu-user at gitter.

Conclusion

These new features will make it much easier to find the relevant information in the docs. There are an infinite number of ways it can be improved and I believe we can compete with major search engines in terms of documentation searching. We don’t need superhero or coding guru, just need people who understand Python, Django and Elasticsearch and have some time to write some code for us. You are a Superhero to us if you can lend your time and effort to improve Read the Docs.

Adding Custom CSS or JavaScript to Sphinx Documentation

2019-07-10T00:00:00Z

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.

Adding additional stylesheets or scripts

If your custom stylesheet is _static/css/custom.css, you can add that CSS file to the documentation using the Sphinx option html_css_files:

## conf.py

# These folders are copied to the documentation's HTML output
html_static_path = ['_static']

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
    'css/custom.css',
]

A similar approach can be used to add JavaScript files:

html_js_files = [
    'js/custom.js',
]

That’s it! You don’t need to create a Sphinx extension anymore to add a bit of custom CSS or JavaScript.

Customizations supported by your theme

I should also note that depending on the theme you’re using and what you’re hoping to accomplish, you may not even need to add custom CSS or JavaScript. Many themes support a number of “theme options” for customizing their look and feel without having to write custom code. For example, here are all the options for the Read the Docs theme and the Alabaster theme which are the two most popular themes on Read the Docs itself.

Both themes, for example, support the addition of Google Analytics to documentation by setting the analytics_id option:

## conf.py

html_theme_options = {
    'analytics_id': 'UA-XXXXXXX-1',  #  Provided in your GA dashboard
}

In summary

To recap, it only takes a few additions to your conf.py to add custom CSS or JavaScript. However, it’s also worth taking a look at your theme’s docs or Sphinx’s built-in HTML options to see if what you’re trying to do is already supported.

Happy documenting!

Read the Docs Offsite 2019

2019-06-20T00:00:00Z

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:

The team at the house we rented in Aruba

The full list of attendees, which is the full-time staff, from left to right:

David Fischer
Manuel Kaufmann
Eric Holscher
Anthony Johnson
Santos Gallegos

Goals

Our biggest goal was building a shared understanding of the vision for the project. Being fully remote, it’s often hard to communicate at a deep level about mission and vision. Being together in person for a week gave us the space to understand each other and our views better.

The other large goal was to build a roadmap for the next 3-6 months for the project. We have often had smaller roadmaps, but never had the chance to discuss all the problems that we encounter with the project, and then prioritize them.

Format

We used the following format:

Before the offsite, we created a Trello board with a list of topics to discuss. This was all the major feature ideas, issues, and concerns that came up over the previous couple months.
For the first 3 days, we went through the list and discussed each topic. We took notes (almost 20 pages) of these discussions, and mostly tried to build a shared understanding on a path forward.
The 4th day we broke each section down into action items, and chunked them into 1-3 smaller sections of work. We called these “v1”, “v2”, and “v3” to break out the stages where each project could be shipped and have impact on our users.
The 5th day we took all the tasks, then sized and prioritized them. We broke things out into 4 piles representing months going forward, and tried to balance the tasks so each month had a similar amount of work in it. We then turned this into a Trello roadmap board.

This worked quite well for us. It gave us space to talk through all the various topics we had, but also gave concrete next steps to move forward on our tasks.

Outcomes

The most valuable outcome is something I said at the offsite:

Before, it felt like we were 5 contributors working on an open source project. Now, it feels like we’re members of a team.

For each member of the team, there was someone else they had never met in person before this. Having all met in person will make it much easier to collaborate online going foward, and to feel like we are working towards a goal that we all share.

In terms of technical output, the roadmap we have established will make us much more productive in our work going foward. The entire team now has vision around the roadmap items, and understands the tasks other people are working on much better. This has already lead to a much better ability to collaborate together.

We are hoping to do another offsite in 2020, and if we do our jobs right, hopefully we’ll have another teammate or two.

New Ad Format Coming to Read the Docs Community Sites

2019-06-18T00:00:00Z

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.

For a while, this wasn’t a problem because we had not reached capacity with advertising. We did not have enough paid advertisers to support the amount of pageviews Read the Docs served. Fast forward a couple years, and our advertising model has proven to be successful. In North America and Western Europe, 100% of pages that are eligible for paid advertising have a paid ad.

Now that we’ve hit that limit, it makes sense to expand to more themes. Rather than going theme by theme as we did in the past, especially considering the huge number of Sphinx themes, we designed an ad that would work across all Sphinx themes. This became much easier with a more simple text-only ad as you will see.

To be very explicit, this new ad format will show advertising on all documentation themes. We plan to roll this new ad format out more widely in stages:

To start with, we are going to enable this ad format for community and house advertising on pages that already have ads on them. As always, we never display two ads on the same page so this ad will be instead of any other ad.
After that, we will allow paid advertisers to use this new format. Again, we will start only on pages that already have ads.
We will email users of custom documentation themes to let them know this change is coming.
At first, we will show only community and house ads on these custom themes.
Finally, we’ll turn on our normal ad rotation to all themes. We expect to complete this by the end of July.

We will closely monitor feedback from document authors, readers, and advertisers during this process. If you have questions or comments on this, please let us know.

Text-only ads

We’ve wanted to try text-only ads for a while but it took time to get it right. From the start, we were very keen on text-only advertisements because they aren’t as obtrusive as image-based ads and they are easier for advertisers to create and experiment with multiple variations. What we didn’t know was whether users would engage with them at similar rates to our other ads.

We ran a small experiment with a text-only house ad on the Read the Docs documentation itself and the results were very promising. Engagement rates were over double our site average and even compared favorably with the same ad in the sidebar including an image. Those figures may not hold up as the format is rolled out more widely but it is certainly a good sign.

A text-only footer advertisement on the Read the Docs documentation

I’d like to thank Eric Berry over at CodeFund for some great ideas and insights around this kind of ad format.

Opting Out

We understand that advertising doesn’t work for everyone – even advertising without any user tracking.

Users can opt-out of paid advertising themselves and for any projects they maintain although they will still see community ads for open source projects and conferences. Gold members of Read the Docs get an ad-free experience and for companies we have our commercial offering at readthedocs.com which is always ad-free.

If you would like to completely remove advertising from your open source project, but our commercial plans don’t seem like the right fit, please get in touch to discuss alternatives to advertising.

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

2019-06-11T00:00:00Z

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.

Advertising without tracking

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.

Despite a slow start to the year, we expect to earn about $75,000 from advertising in Q2. This brings our advertising revenue back to the level before our ads were added to major ad blocking lists last year.

While we do earn money from other sources such as our commercial offering, advertising continues to be our largest source of revenue and has allowed us to expand our team to five full-time people. Compared with three years ago when we were scraping along with very little money, our community issue tracker and support requests receive prompt responses.

Progress

We’ve made great progress on advertising over the past year.

We survived a major hit to revenue from ad blocking without resorting to cat and mouse games of changing ad layouts and APIs to avoid ad blockers.
Our community ads program has been significantly expanded. We are actively running free community advertising promoting over ten open source projects and conferences.
While we never tracked users with advertising, we put in place stricter Do Not Track privacy protections. We continue to believe that advertising can be well targeted without tracking users.
We launched an advertising vertical to let companies promote their open jobs to developers.
Our advertising revenue share program tripled in size.

Our ethical advertising approach, with no user tracking, has been key to our sustainability and has allowed Read the Docs to continue to build new features and give back to our community.

What’s next

We have some really interesting developments coming regarding ethical advertising.

We are looking to add a few more projects to our ad revenue share program and help more projects reach sustainability with an ethical advertising approach. If your project on Read the Docs does 100k+ pageviews per month and you are interested in exploring a new revenue stream, please let us know.

We are testing a new text-only ad format which we will detail in a future post. Text-only ads are something we’ve wanted for a while because we believe they are less intrusive to readers but easy for advertisers to experiment with multiple variations. So far the results have been very promising and we are planning to roll this out more widely.

Our ethical ad network is getting closer to launch. It’s a shame, but there’s a critical lack of funding for open source projects that form the building blocks of some extremely valuable software. We believe that advertising can fill some of that gap and Read the Docs can help by sharing some of the lessons we’ve learned building our own advertising. If you know a site that might be interested in being a beta tester of a pro-privacy ad network built specifically to help fund open source, please get in touch.

Thanks

Advertisers always have a choice where to direct their marketing spend and for many of them it would have been simpler to just go with the usual behemoth advertising platforms rather than advertising with a niche site like Read the Docs. I want to thank all our advertisers who believe in our approach and continue to support us.

Would your company like to reach a 100% developer audience?

Over 7 million developers Read the Docs each month. Get in front of them today!

New Configuration File

2019-02-20T00:00:00Z

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

version: 2
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt
sphinx:
  configuration: docs/conf.py
formats: all

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

Using the web interface is quick, but the main advantages of using a configuration file over the web interface are:

Some settings are only available using a configuration file. We are moving away from using the web interface.
The settings are per version rather than per project. This would allow different versions of docs to be built with different versions of Python or different requirements.
The settings live in your VCS.
Reproducible build environments over time.

What did we change in the new version?

All the configurations from the web interface. In the past not all options from the web interface were available in the configuration file, now they are! We also reorganized and renamed some options to make them more clear.

New defaults, we don’t merge the values from the web interface, because this was confusing our users. This also allows us to change defaults without breaking existing projects.

More flexible installations, users can install their projects in a more flexible way, like multiple requirements and packages from different locations.

Strict validation for invalid options in the configuration file, to avoid typos and provide more feedback on invalid configurations.

New features

MkDocs support (previously it was only supported from the web interface).

version: 2
mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: true

More control over Sphinx.

version: 2
sphinx:
   builder: html
   configuration: docs/source/conf.py
   fail_on_warning: true

Control over submodules, we don’t always need them all to build our docs.

version: 2
submodules:
  include:
    - third-party/dependency
  recursive: true

Support for multiple packages/requirements installations.

version: 2
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt
    - method: pip
      path: package

Future improvements

We are already planning new features to support more projects and use cases.

Pipfile support, this is one of our more requested features, and we are going to ship it soon. Keep an eye in #3181.

Show the configuration used in each build. We want to make more explicit to the users how we are building their docs.

Redirects per version of your docs. Currently users can define global redirects only from the web interface, this is hard to maintain and review. One use case is when you change your docs structure between versions. Keep track of this upcoming feature in #4221.

Start using it

The full docs about the new version are available here.

If you are using the v1, you can update to v2 following our migration docs.

If you have a problem using the configuration file, feel free to file an issue.

Summer internship

This project was part of my summer internship in Read the Docs, it was held at the same time as the Google Summer of Code (GSoC) project.

Thanks to the core team (Anthony, David, Eric, and Manuel) for helping me in the process. Thanks to all contributors, sponsors, donors and users of Read the Docs to make the project sustainable.

Tips for Getting a Developer Interview

2019-02-13T00:00:00Z

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.

Rather than covering how to crack developer interviews or how to gain the necessary technical skills, these tips will focus on getting your foot in the door. Specifically:

Making your application stand out
Improving your application response rate
Getting to the interview process

When applying, go deep not wide

“I don’t want candidates who drive by job sites and pepper every job they find”

As a candidate, there is a temptation to play the numbers game and apply to as many jobs as possible. Many jobs sites make it easy to apply to many jobs quickly and this gives you that feeling that your job search is progressing.

Based on what hiring managers told us, playing the numbers game isn’t the best approach. While it is a bit of a job-seekers market, especially for more senior talent, companies are looking people who want to work for their company and who believe in their mission. Hiring managers told us they want applicants who “think about the company, then check for opportunities”.

That’s almost 300 applications in 2 weeks on just one of the job sites where this is posted.

Spend a little more time on your application

While it takes longer to apply to a job post that requires a cover letter or requires answers to a few questions, those are great ways to have your application stand out relative to other applicants. You don’t want your resume to get lost in a stack of hundreds.

As we mentioned last time, quite a few hiring managers we talked to started requiring a cover letter or even just a couple questions that are unique to the company in order to make their job filtering candidates easier and get candidates who want to work there not those who just want a job.

All the companies we talked to said when they post a job they got tons of applicants, but that high quality, qualified applicants were still in short supply. When 200 people apply to a job but only 20 are willing to do a cover letter, a hiring manager can spend a lot more time per candidate with the smaller pool. One hiring manager told us explicitly “fewer resumes is better because there’s less noise”.

While I know I said getting a developer job isn’t a numbers game, this doesn’t strictly mean you can use these techniques to apply to 2-3 jobs and you’ll get hired. Sometimes by the time you apply, somebody is already in the final stages of getting hired. The position may not really be open anymore. Don’t get discouraged in your job search. Finding the right match can take time.

Here’s some of the questions from the DuckDuckGo application process. This is your place to stand out! DuckDuckGo was not one of the companies we interviewed.

Make yourself a referral: use your network

Hiring managers universally told us their top recruiting channel is referrals from existing employees. As a candidate, use this knowledge to your advantage and make yourself into a referral hire.

Did you see an acquaintance on social media post about job openings at their company?
Does a friend or a friend of friend work at the company?
Do you have a first connection (or a very good 2nd connection) on LinkedIn who works there?

In all of these cases, you should contact that person before applying. Even if the person you know isn’t on the hiring team, your contact might be able to put you in touch with the right person.

“Most [senior] people go through their network”

For a mid-level to senior candidate with 7+ years of experience, this is even more important based on our interviews. At that stage of your career, hiring managers we talked to expect a high quality candidate to do due diligence on the company and team to make sure it’s a mutual fit.

Regardless of the exact route you take here, getting in touch with the right people to learn more about the team, the tech stack, and the company makes it clear that you’re very interested. You’re far more likely to get a response, move on to the interview process, and ultimately get hired.

Establishing contact with companies

Turning yourself into a referral is easier for a senior candidate. But what if this is your first or second job or don’t know anybody at the company?

After referral candidates, the next best hiring channel in our interviews was local meetups and engaging the local community. Both startups and established companies – especially when they are actively hiring – use meetups to find talent. If you’re able to meet the hiring manager in person or establish some sort of connection, in my experience, this raises your chances significantly.

In our interviews, another channel that mid-size and larger companies we talked to used to recruit was to rely on their presense at conferences. For many companies, recruiting was the primary motivator to sponsor a conference and have a booth. As a candidate, talking to the engineers at the booth and showing interest can ensure that your application doesn’t get lost among all the applicants they get.

At a smaller company, it’s frequently possible to figure out exactly who the hiring manager is from some combination of the website, hiring posts, and LinkedIn. This is a great way to make a valuable connection and make sure the role is a good fit. Contacting the hiring manager cold requires a bit of finesse so make sure to be respectful.

Places like the monthly HackerNews Who’s Hiring thread are fantastic because they allow direct interaction with the hiring manager and many companies list a person’s direct email to inquire about a position, learn more directly from the source, and show you’re interested.

Here’s some of the phrases we heard from hiring managers in interviews.

Conclusion

By spending a bit more time on your application, establishing contact with the company, and asking good questions about the work and team, you are showing your intent and interest in the company.

You want to make sure the hiring manager or recruiter understands that you’re a serious candidate and you want to work there on their team. Using these methods will improve your response rate and help you get the interview. By doing a one-click apply on a job site, this is completely lost.

Thanks

Again, I’d like to thank all the hiring managers who took the time to talk to us.