Read the Docs Blog - Posts from San Diego, CA

War in Ukraine and what it means for Read the Docs

2022-03-07T00:00:00Z

With news surrounding the invasion of Ukraine evolving rapidly, we felt it was necessary to provide an update to our users and customers.

At Read the Docs, we are outraged and saddened by the invasion of Ukraine and we condemn this act of violence as wrong and unlawful. We are monitoring the situation in Europe and how it relates to our employees, customers, and our services to the open source world.

Read the Docs is a very small company, with only seven employees, and fortunately none of them are currently in harm’s way. Our impact on the open source ecosystem, however, is bigger than our size, and we have users all over the world, including in Ukraine and Russia.

Impact on our services

We are continuing to monitor news that could potentially affect our users, including sanctions applied to the region.

Read the Docs is currently partially blocked in Russia by the Russian government. While we are working to resolve this, it does not appear that this block is related to war in Ukraine.

Other than this government block and potential effects from financial sanctions, our services are not impacted. Read the Docs is hosted and incorporated in the United States, and so any further changes to US sanctions would apply to our services.

What we are doing and what you can do

As the situation develops, we will be transparent about any actions we take. We take our role of helping the open source community with documentation seriously and we aim to be a platform for all developers.

Over the coming days, our advertising arm EthicalAds will be running a series of community ads aimed at raising money for the United Nations Crisis Relief Fund and other missions aimed at humanitarian aid for Ukraine. If you can donate to help provide humanitarian aid, please do.

We are hoping that peace is restored as quickly as possible.

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.

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.

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!

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!

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.

Lessons From and For Hiring Managers

2019-01-30T00:00:00Z

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:

Have a strategy for getting more referrals whether that is actively asking employees or having an overly generous referral bonus. Referrals are probably your top source of candidates so figuring out how to get more will save you time and money in the end. Then do the same for your other best recruiting channels.
Reach passive candidates. There are a lot more passive candidates than active ones so have a plan to reach them. Great developers (especially senior ones) probably aren’t actively looking for a new job and it’s a job-seekers market. Even if somebody isn’t considering a new job at all, the next time they do, you want them to think of your company.
Recruiting for diversity is a focus for hiring managers. Put together a concrete plan for getting more diverse candidates and meeting your diversity goals. Engaging with local developer communities and nonprofits and encouraging referrals worked well for companies we talked to.
Get more signal in your application process by adding a step such as a cover letter, quiz, or simply add a couple questions folks have to answer. Making candidates spend even one extra minute on their application can save you hours filtering resumes.

Why is Read the Docs tackling hiring? Hasn’t that been done?

While we didn’t initially think about Read the Docs ads for recruiting, based on some unexpected past successes, we decided to position promoted jobs as one of our main verticals within our advertising. Rather than dash forward and create a product, however, we started by just talking to hiring managers to understand the hiring process better so we can best meet their needs with something we create.

One of the questions we asked in our interviews was how long it took to hire their most recent developer? Specifically, we asked hiring managers to consider how much time they and their team spent sourcing candidates, filtering resumes, preparing for and doing phone and onsite interviews, and anything else. Internal recruiters’ time is valuable too, but we figured the hiring manager would probably underestimate how much time the recruiter spent since they didn’t directly observe it. While answers were all over the place, the range with the most overlap was 50-100 hours of engineering time to make a hire. No huge revelation here, but companies make a massive investment in hiring.

From my days being an interviewer at Qualcomm and Amazon as well as a smaller startup, I’d say fifty hours is on the low side for big company but about right for a smaller company. When something costs 50+ engineering hours to do, any improvement is worth a lot of time and money and at Read the Docs we believe we can help significantly here.

Top hiring channels

It was no big surprise to hear that referrals were the top hiring channel. The second best channel was a bit of a surprise with local meetups and local communities being very high in a majority of interviews although this was less true among the largest companies we talked to. Companies also had some success with recruiting at conferences, using various job sites, and proactive outreach.

Hiring managers shared strategies with us that they used to increase the number of referral and community candidates they got. Two different companies we talked to hosted multiple local meetups at their offices and one of those hiring managers said “being plugged into the community” was their main channel for hiring.

Another hiring manager who focused a lot on developers with security experience talked about having “LinkedIn parties” where either a hiring manager or internal recruiter sat with engineers on their team one-on-one to go through their LinkedIn network. Even when he heard a person “is great, but they’ll never change jobs”, that was a good candidate to target. Security is such a high demand field, he said, that very few great people are actively looking for a job.

Reaching people who aren’t looking is critical

One of our biggest takeaways from the interviews was that companies wanted to reach candidates before they started actively looking. Most of the hiring managers we talked to stressed the importance of getting in front of passive candidates. Certainly fewer people are actively looking for developer jobs than those who are just open to a change. A few different reasons were given but I actually think Joel Spolsky had it right when he said top developers “barely ever apply for jobs at all. That’s because they already have jobs.”

This quote isn’t necessarily a slight against people who apply actively to jobs. Virtually everyone I know in tech started their career applying to a job. Rather, the message here is that as a developer becomes a mid-level developer and then becomes a senior developer, they are more likely to rely on their network to somewhat passively job seek rather than going through the front door and simply applying on a company website.

Reaching people who aren’t actively looking is one area where Read the Docs can really help. Companies want to reach them when they are just thinking about a new job or perhaps passively seeking. Developers who come to our site are actively building software, not job-seeking. Many of them are content at their current position. For those that aren’t, this is a perfect place to showcase great companies and help Read the Docs’ visitors to find their next job.

Recruiters can be worth it

In each interview, we asked whether the company used recruiters or recruiting related services (eg. Hired, Triplebyte). Universally, hiring managers brought up how expensive recruiters are, but most of the people we talked to who had actually used recruiters in the past had a positive impression overall. Hiring takes a ton of time, typically from senior folks at the company. At smaller startups, that’s frequently the CEO or CTO. Even though the price is high, recruiters who help speed that process along are worth it.

I think the quote that really summed it up was from a VP of engineering at a startup that just raised a Series B. He’s trying to grow his team by 10 developers this year (about a 50% increase). His experience hiring his first couple developers through a 2-person boutique recruiting firm was great and he would use them for hiring everyone “if hiring 10 people didn’t mean $100k+” in fees alone.

Full disclosure: Triplebyte is an advertiser on Read the Docs. We’re fans.

Diversity and inclusivity in hiring

We didn’t ask any questions around hiring for diversity but fully six hiring managers volunteered information on their companies’ strategies for getting more diverse candidates. This is why I love this kind of interview where the goal is just to listen to what hiring managers say and dig deeper when you hear something interesting. Some of the larger companies we talked to had explicit diversity goals set at the company level. Even among the hiring managers at smaller companies, they shared some tactics they used to get more diverse candidates to apply.

Of the companies with hard diversity goals, most of them told us that their strategy entailed syndicating their job openings to diversity focused jobs sites or in some cases engaging directly with relevant interest groups. In terms of efficacy, reviews of these various jobs boards was mixed.

On the more positive side, hiring managers cited Girl Develop It, Black Girls Code, and PyLadies as fantastic channels for both increasing candidate diversity and for high quality applicants. Two companies also talked about trying to decrease bias in their job postings using Textio and similar services.

Having multiple people mention diversity completely unprompted really shows that this topic is becoming higher priority for companies and hiring managers. It also shows that it if hiring for diversity is important to your company, you need to have a plan for actually making those goals a reality. It’s worth checking whether the strategy actually works too.

Remember, sourcing is the bigger problem

Every single hiring manager we talked to complained about the time they spent filtering resumes from applicants. Some choice quotes I heard included “95% of applicants weren’t a fit” even after only reviewing the resume and a hiring manager who posted to a very popular remote-only job board told me he got “literally one thousand applications”. While I believe this is a legitimate complaint, I think Aline Lerner, founder of interviewing.io said it best when she said “Engineering hiring isn’t a filtering problem. It’s a sourcing problem.” The reason we heard it a lot is that filtering is a very time-consuming task that hiring managers directly deal with.

The real problem here is that the number of applicants to a job post is a vanity metric. What hiring managers are looking for is qualified applicants, which is harder to gauge without some additional work. One of the problems here is that a lot of jobs sites make it really easy for candidates to apply to lots of jobs. This is understandable from their perspective as more applicants makes their platform seem more valuable. There’s no reason for a job board to put artificial barriers into the application funnel, but hiring managers told us they want candidates who want to work for their company not somebody who is applying to every job out there.

Instead of building product here, I think hiring managers just need a few tweaks to get more of a signal of candidate quality and intent in their applications. A few of the hiring managers we talked to described how they did this. Multiple hiring managers mentioned how they required a cover letter that answered specific questions (“why us” was the most popular). Another hiring manager described how his hiring system just asked a few short questions of candidates – for example, “what is the software project you’re most proud of” – when they applied. When a candidate didn’t do a cover letter or didn’t answer the questions, they weren’t considered. The latter solution seemed like the best of both worlds as it solves the one-click apply problem without being too much of a barrier.

Thanks

I’d like to thank all the hiring managers who took time out of their days (or in some cases evenings) to talk to us. If you’re a hiring manager or an internal company recruiter and you’d like to share your experiences and help Read the Docs, please get in touch.

Check back soon for our next post in this series which covers tips for candidates based on the same interviews!

Update: This blog was updated to mention our new post in the series

Ready to hire your next developer, fast!

Get in front of passive candidates already using your tech by promoting your job openings with Read the Docs.

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.