Job Descriptions

You’re reading an excerpt of The Holloway Guide to Technical Recruiting and Hiring, a book by Osman (Ozzie) Osman and over 45 other contributors. It is the most authoritative resource on growing software engineering teams effectively, written by and for hiring managers, recruiters, interviewers, and candidates. Purchase the book to support the author and the ad-free Holloway reading experience. You get instant digital access, over 800 links and references, commentary and future updates, and a high-quality PDF download.

A job description outlines the main features of an open position at a company, including the work the future employee will be expected to do, expectations for applicants, and ideally, a number of reasons a candidate should want to apply, including a description of the company’s mission and the benefits offered. It also typically includes the position’s title; it may or may not disclose its compensation. The job description may be in the form of a single-page statement, or a position may have a marketing-like web page to it. The hiring team may create a few versions of each job description, so that people can share it externally across a variety of platforms, like career sites, job boards, and the company website. A well-written job description should give an accurate picture of the role, and entice desirable candidates to apply.

​caution​Writing a job description before having had any conversation with your team or colleagues is a common pitfall; it’s essential to understand the role you are hiring for and the value proposition of the company, and to be aligned internally on each. If a candidate meets with interviewers who all have different ideas of what the role is or why the person might want to join the company, this leads to confusion, a poor candidate experience. It’s also inefficient. It’s critical to have clarity on the position’s target level and compensation before advertising for the job.

​important​ Many large companies offload the responsibilities of writing the job description to a recruiter. You know more about your company, the role, and your ideal candidate than the recruiter does. The most effective way to craft a great job description is for the hiring manager to work with the recruiter directly whenever possible.

Crafting the Job Description

While every job description will have its own set of unique details, there are a few basic principles that you can use repeatedly as you continue to hire. (Many of the practices in writing good job titles also apply to writing good job descriptions.)

Anatomy of a Job Description

An informative and compelling job description may have some or all of the following elements:

• job title

• job level

• location (and/or “remote friendly”)

• company name (including logo or branding, if available)

• company narrative

• role narrative

• outcomes expected for the role

• skills and/or experience required to meet expected outcomes

• skills and/or experience that is preferred but not necessary

• traits and values of the ideal candidate

• compensation, benefits, perks

• how to apply

• EEO statement.

Depending on your priorities, you may spend more space on one or another of these elements, or combine some of them. How you choose to structure these elements typically indicates a lot about the company’s priorities and even their hiring philosophy: Does the job description focus on a long list of requirements first? Does it describe the ideal candidate up front? Or does it begin with a detailed description of the company’s mission, or conversely, omit it?

If you’ve already established the outcomes of the role and the skills, characteristics, values, and experience that will make success in the role likely, listing these in the context of a job description will be relatively easy.

​caution​ Be mindful of length. Candidates will often skim quickly and may not even make it to material lower on the page. Put what you most want your ideal candidate to read at the top—is it the company’s mission, the candidate’s traits and values, their required expertise, or something else?

Here’s what that can look like in practice, from a Splice job description for a Software Engineer position:

Figure: An Annotated Job Description

Source: Splice; annotation by Holloway

Balancing Outcomes and Requirements

A key goal is to find a balance between making the role description too broad (which may make it less enticing to candidates with a specific set of experiences and interests) or too narrow (which can cause candidates who may have been a good fit to self-select out).

If your job description is built around checklists of requirements, it will be a lot less compelling to candidates than if it is built around the challenges and impact of the work—the outcomes.

Experience requirements are tempting to use because they are concrete, so someone on your team can easily compare a candidate’s profile to the experience required. Likewise, candidates can look at the required experience and decide whether or not to apply. But experience may not always translate to ability or even seniority, so you may wish to be more specific about the kind of experience you are looking for.

For example, if you’re looking for someone with “5+ years of C++ experience,” you might end up spending a disproportionate amount of time assessing candidates’ C++ skills (and probably will struggle to attract the best candidates). But if you focus on the outcomes for the role, you might say something like, “successfully develop and scale microservices handling 10M requests per day.” This description can help to filter out candidates who don’t have enough experience to be able to accomplish that kind of work, while leaving the application open for the kind of experience that might surprise you.

​caution​There is research indicating that certain candidates may take requirements more literally than others—in particular, women may be less likely to apply if they don’t meet all the requirements listed for a job. There are plenty of anecdotes of companies themselves not taking the requirements they list literally. Only use requirements if they are truly requirements; and when you do, it can be helpful to list which requirements are “minimum requirements” and which are simply “preferred.” For many roles, a degree in computer science may be preferred, for example; but there might be plenty of qualified candidates who don’t have one. If you don’t really need it, consider not including it at all.

Remember, this is all about finding candidate-company fit, not about enticing the “best” people to join your team.

Fairness and Inclusivity

​danger​ Wording in your job description can have unintended consequences in determining who applies. Attempts to make your roles sound more enticing can actually discourage people from applying. Researchers have found evidence that using gendered language contributes to an imbalanced pipeline of candidates; certain language can also discourage older candidates or candidates from marginalized communities from applying.

To avoid this, it’s critical to think carefully about your word choice and test your wording on a variety of people. There are also tools like Textio that you can use to check your text for discriminatory or biased language.

​important​ There are a number of ways in which you can make your job descriptions and company About pages more inclusive, thereby increasing the number of qualified candidates who will be interested in working for you. These include the job description format, its language, the company’s value proposition, and how the company talks about Diversity and Inclusion on its website or in the context of the job description.

Should Job Descriptions Include Salary Information?

​controversy​ Many companies include such compensation details as benefits, time-off policies, and perks like remote work, gyms, and free lunches; but they rarely include specific salary information.* While a small number of tech companies (like Glitch and a handful of others) and all U.S. government agencies do, most organizations prefer not to include salary data so as to allow room for negotiation. Salary transparency in job postings might also reveal inequities in the pay structure for existing employees.

Many recruiting and HR experts advocate for putting salary information in job descriptions, noting that this reduces the amount of time you have to spend screening early in the process, and leads to better retention rates and more productive, satisfied employees.*

Candidates prefer to know the salary up front, or they risk wasting their time applying for a position that cannot meet their needs. In a candidate-focused hiring process, it’s worth considering including the expected salary, a salary range, only the lower bound (assuming candidates will negotiate up), or only the upper band (“up to” X amount). Of these choices, a salary range is most often what specialists recommend.*

Sharing information about salary can be positive for companies: As reported by Dice, in an A/B test Stack Overflow found “ads that featured a salary range experienced a 75% average increase in click-through rates. Even jobs that advertised salaries below $100,000 saw a 60% increase.”*

Another concern competitive companies express is that including high salaries will bring in a whole lot of unqualified applications. This may well be true. In the same Dice report, the company Proforma is said to have found an increase in the number of unqualified applicants when they included salary ranges. However, it also ultimately increased the efficiency of their hiring process: “My closing rate has jumped from the mid-40% range to 84%, so I’ve more than made up for the extra time I spend screening applicants,” said Proforma’s Director of Career Advancement.

​startup​ If you’re worried about not being able to offer a competitive salary, it’s still not wise to avoid including it. Candidates will find out sooner or later, and keeping them in the dark will build bad will and may cause them to withdraw from the process. Instead, it’s best to include the salary or a band, and bring attention to other parts of your job description—if you’re highly mission-driven, emphasize why the mission matters; state that you offer competitive equity packages and benefits; and include narratives about the team and the impact they’re having or working to have. Your transparency alone may be attractive to candidates.

The EEO Statement

​Definition​ An equal employment opportunity statement (EEO statement, equal opportunity employer statement, or diversity statement) is an expression of a company’s compliance with federal equal opportunity law, which is administered and enforced by the Equal Employment Opportunity Commission (EEOC). Only federal government contractors and subcontractors are required to include EEO statements in their job descriptions,* but many other companies do so voluntarily.

The advantage of EEO statements is that they show the company is operating in good faith—but they’re also part of how the company markets itself. Companies often opt to make the EEO statement specific to the company’s values, even if their practices do not always comply.

Examples of EEO statements:

• Basic: “Acme Corp is an equal opportunity employer.”

• Google: “At Google, we don’t just accept difference—we celebrate it, we support it, and we thrive on it for the benefit of our employees, our products, and our community. Google is proud to be an equal opportunity workplace and is an affirmative action employer.”

• Dropbox: “Dropbox is an equal opportunity employer. We are a welcoming place for everyone, and we do our best to make sure all people feel supported and connected at work. A big part of that effort is our support for members and allies of internal groups like Asians at Dropbox, BlackDropboxers, Latinx, Pridebox (LGBTQ), Vets at Dropbox, Women at Dropbox, ATX Diversity (based in Austin, Texas) and the Dropbox Empowerment Network (based in Dublin, Ireland).”

• Dell: “Dell is an Equal Opportunity Employer and Prohibits Discrimination and Harassment of Any Kind: Dell is committed to the principle of equal employment opportunity for all employees and to providing employees with a work environment free of discrimination and harassment. All employment decisions at Dell are based on business needs, job requirements and individual qualifications, without regard to race, color, religion or belief, national, social or ethnic origin, sex (including pregnancy), age, physical, mental or sensory disability, HIV Status, sexual orientation, gender identity and/or expression, marital, civil union or domestic partnership status, past or present military service, family medical history or genetic information, family or parental status, or any other status protected by the laws or regulations in the locations where we operate. Dell will not tolerate discrimination or harassment based on any of these characteristics.”

This is an interesting, if niche, topic. If you’d like to read more about EEO statements:

• “Why EEO statements fall short” (Workable; this is a great introduction to the topic and includes analyses of EEO statements, including Dell’s)

• “The Unintended Consequences of Diversity Statements” (Harvard Business Review)

Creating Narratives

The job description is a tool for reaching toward candidate-company fit: it is as much about the people you hope will apply for the role as it is about the company. The job description exposes your company—possibly for the first time—to the candidate pool, so it’s crucial to think about how you are representing the value proposition of your company and team through this medium. At the same time, a good job description will be designed to find and attract candidates who are both qualified for and interested in the role. The best way to do this is to build narratives—that is, telling stories—about the company and the ideal candidate.

Storytelling doesn’t come naturally to everyone; it’s easy to do too little, with a list of requirements awkwardly crammed into a character study, and too much, with a grandiose story that doesn’t map to people’s expectations about the nature of their work. After all, you’re hiring people to solve engineering challenges, not fight dragons. And odds are, you don’t have a writer on staff to help you craft these artifacts. For a smaller company or team, you’re probably best off having everyone, even non-engineers, review the job description to make sure the mission, company narrative, and role narrative feel right. Larger organizations might already have enough experience writing these that you’ll have a bank of options to choose from, but that doesn’t mean what you’ve been working with has really been effective. It may be time to update your story for the next great candidate.

Company Narrative

People want to be emotionally engaged in your story, and the journey of your company, and the arc—and to feel like it’s on an upward arc.Aileen Lee, founder, Cowboy Ventures*

The company narrative is a concise expression of how a company wants to be perceived—that is, a distilled version of the brand it hopes to project. It typically describes the company’s mission, which may be supported by an origin story and a statement of the company’s vision. A company narrative may also include a brief pitch about what it’s like to work there and what values the company holds.

The story you tell about your company is one of the more powerful ways to convey your values and brand to a candidate. To be effective, it needs to be concise (a paragraph or two at the most) and evoke an emotional reaction. Standard corporate boilerplate won’t attract curious candidates—neither will descriptions that are heavy with company jargon. Consider this example from Jan Tegze at SourceCon:

Which company would you like to join? ‘We are an international company focusing on space with offices across the globe, and our goal is to send people to other planets.’ Or the second company, ‘Our company was founded under the belief that a future where humanity is out exploring the stars is fundamentally more exciting than one where we are not. Today we are actively developing the technologies to make this possible with the ultimate goal of enabling human life on Mars.’Jan Tegze, author and Senior Recruiting Manager, SolarWinds*

Both descriptions are for SpaceX; the second is directly from the company, and the first is a version of it that Tegze wrote based on common pitfalls in how companies write about themselves. His version is a collection of facts, while SpaceX’s version is an actual story, grown out of the company’s origin, mission, and unique vision.

Here are a few questions to get you started building your company narrative:

• Why does the company exist? Why does it matter? What is the founding story?

  • If you’re the founder of a company, think back to what you told investors or your first customers. What was the problem you saw, and why did you choose to solve it? Why are you the right person or team to solve it?

• Why will the company be successful? What unique attributes does it have, and what has it accomplished so far to prove that it can succeed in the future?

• What is your personal story with the company? Why did you join and why are you excited about it?

• Why do current employees choose to work for this company instead of any other?

You won’t use all of this—your narrative will be shorter—but these questions can get you thinking about what your ideal candidate will most want to hear.

In “The Power of Company Narratives,” management expert John Hagel provides hypothetical examples of these narratives, and identifies two key elements of great company narratives:

• They are open-ended: there is no clear resolution to the story.

• The narrative is about the intended audience (the candidate), not the organization telling the story.

Rather than being strictly about the company, a great company narrative connects the mission to the work the candidate would be doing to tackle that open-ended challenge. (For an even more in-depth look into company narrative, we recommend Hagel’s post on narrative as a “powerful agent of pull.”)

Obviously, if you are a hiring manager at a larger company, branding will already have been established and you most likely will have a lot less power to change the company story. It still might be helpful to consider whether the company story can be adapted to suit this role and the kinds of candidates you’re hoping to bring on.

Example Company Narratives

Many job descriptions lead with their company story first, to help get the candidate familiar with its goals and values and hopefully generate intrigue or excitement about joining the team. Here are a few examples of brief, compelling company narratives we pulled from job descriptions for engineering roles. Notably, each of these avoids company-specific jargon that can be alienating to candidates:

• Nike. NIKE, Inc. does more than outfit the world’s best athletes. It is a place to explore potential, obliterate boundaries and push out the edges of what can be. The company looks for people who can grow, think, dream and create. Its culture thrives by embracing diversity and rewarding imagination. The brand seeks achievers, leaders and visionaries. At NIKE, Inc. it’s about each person bringing skills and passion to a challenging and constantly evolving game.*

• Splice. We’re building a creative ecosystem for music producers. With this ecosystem, we’re cultivating a global community of creators that fosters inspiration, connection, focus, and growth.

  Our work environment is no different. We champion collaboration, big ideas, helping where we can and asking for assistance when we need it. We aim for steady, measured expansion through experimentation and iteration. We encourage optimism, inclusion, and transparency in the workplace. We aren’t afraid to stumble, because every stumble can teach us something about our processes, strategies, and even ourselves.

  We don’t just hire people who mirror our culture. We hire people who add to it.*

• Nordstrom. We’re a fast-moving fashion company that empowers our people to be innovative, creative and always focused on providing the best service to our customers. The retail industry is rapidly changing, and we have interesting, complex problems to solve every day—from developing cutting-edge technology and opening new stores, to designing fresh, must-have fashion.*

Appendix B has more on building your company’s value system and sharing it with the world.

Additionally, the Holloway Guide to Raising Venture Capital offers guidance on building mission and vision statements.

Role Narrative

A role narrative is a short story that appears in a job description and appealingly illustrates to potential candidates—especially the company’s ideal candidates—what it would be like to work in the advertised role. It may describe the outcomes of the role, how the role would benefit the candidate, why the role exists, characteristics and skills that will help a candidate succeed in the role, and the role’s organizational context. Role narratives are often written in the second person, addressing the candidate as “you” to allow them to envision themself in the role.

In addition to a narrative for your company, it will also be helpful to develop a story for each role. The process of considering all the elements of a role, including candidate personas and whether your company is interested in certain types of candidates, should lead you to be able to answer the following:

• Why does this role exist? Why is it needed now?

  • How will the role impact the company and the wider world?

  • What challenges will this role help the team face? Why is that work exciting?

• What skills or characteristics does a candidate need in order to succeed in the role?

  • Are you looking for an up-and-comer? Someone motivated by the company’s mission? Someone very self-motivated? Someone with specific experience?

• What benefits does the candidate gain in taking on this role?

  • What sorts of challenges would the candidate work on?

  • What growth and learning opportunities does this role provide?

It’s easy to fall into the trap of merely describing the factual details of the role, but answering these questions in a job description helps place the candidate as the protagonist in a story. This provides imagery and concrete details that lead the person to imagine jumping into that role, tackling the challenges, and working for a company they’d be legitimately excited to join. It’s motivating instead of merely intimidating.

Example Role Narratives

Here are some examples of well-crafted role narratives:

• Culture Amp:* Senior Software Engineer (Front end), Payment Platform Web

  We are searching for experienced frontend engineers to join our team in Melbourne, delivering new and updated product features in our JavaScript and CSS codebases.

  Depending on which team you join, you may work with React (typed with TypeScript or Flow), Apollo GraphQL, Redux or even the newest addition to our frontend stack, Elm (no experience required!). For styles, we use CSS Modules written in Sass, which our React and Elm components are able to share. We write JavaScript tests in Jest, Elm tests with elm-test, and end-to-end feature tests with RSpec and Cucumber. We also have a suite of visual regression tests, that automatically catch CSS bugs across our entire browser support matrix. Our back end is Ruby on Rails, with a growing constellation of microservices written in Ruby and Elixir.

  You should love crafting beautifully designed and intuitive user experiences, and believe that creating well-tested, clean code is just as important for the front end as the back end. You should enjoy being surrounded by talented engineers, learning from others, as well as contributing to their development. To top it off, we hope you’ll share our passion for culture and changing the world of work for the better.

• Netflix:* Engineering Director - Netflix APIs

  Our API strategy has paid off in our consumer product offering. Signup and content discovery experiences on TV, mobile, and web rely on the API layer to provide their data and functionality. Hundreds of A/B tests are supported through this API. Millions of devices interact with it every day. We’re not done yet, though; as Netflix grows the needs of the API layer continue to evolve. You would guide the team in exploring ideas like API federation, alternate protocols and query languages like GraphQL, and many more ideas for how to accelerate our API development velocity.

  This past summer we made a new strategic bet—the patterns behind our consumer product API success could similarly pay off in our studio product. Netflix’s studio product is a suite of applications that enable content production, from the idea stage to a finished film or series, for 100s of Netflix originals each year. We formed a new group focused on building and scaling API layers for studio applications in addition to consumer applications. Come lead this combined group that is driving Netflix’s API evolution.

• Square:* Senior Software Engineer (Frontend), Payment Platform

  Commerce is changing, and as part of that Square is transforming from a product company to a platform company. If you join now, you will ride the massive wave of omnichannel retail combining in-store and online / in-app payments. You’ll help create an “AWS of Commerce” as our developer platform exposes core primitives for other companies to build on top of. And you’ll have a great experience with our motivated, friendly, and diverse team.

Where to Post Job Descriptions

Along with posting job descriptions on your own site (typically in a careers or “work with us” section), you may consider posting in a number of common places that candidates look when conducting a job search.

Table: Where to Post Job Descriptions

See Appendix B for more details about promoting jobs, which can be done more broadly via blogging, social media, at events/hackathons, and more.

​important​ While crafting great job descriptions for platforms like these is important, most jobs aren’t advertised; an estimated 70–80% of jobs (across industries) are only available through the hidden job market—networks and social media. The pitfall of relying on the hidden job market to find candidates is that that pool is small and will typically be pretty homogenous. Posting job descriptions gives great candidates the opportunity to find you, without having to be part of your in-crowd.

Job Description Examples and Resources

Here are some valuable examples of job descriptions we like and why we like them:

• The social media management company Buffer has an interesting approach to job descriptions. Even when they have no job openings, their company website maintains a full page dedicated to telling the company’s story in a way that anchors the reader as a potential character in that story. The page begins with a short story about Buffer, then tells the reader where they could work, what the team is like, benefits the company offers and the values it holds. By the end, someone who’s really drawn to working there will already be picturing joining the team and can get on a waiting list to find out when new roles open up.

• Stripe: Most of Stripe’s job descriptions start with the company’s mission and/or the team’s goals, and then share the objectives and impact of each role. This is a lot more compelling to candidates than just listing qualifications, which are still included, but come later in the description.

• Splice: These job descriptions not only help candidates concretely understand the role (“What you’ll do”), but also set expectations about how the process will look (“How we’ll handle your application”).

• Culture Amp: This company clearly put quite a bit of effort into their role narrative, and additionally links out to other things they’ve written on the culture at their company.

• LinkedIn’s Recruiter Toolbox: This resource includes tips, templates, and different examples of job descriptions.

• LinkedIn’s Talent Solution Template: This is another example from LinkedIn that uses the sequence of objectives, responsibilities, required qualifications, and preferred qualifications.

Further Reading on Job Descriptions

Here are some additional resources for writing great job descriptions:

• “Software Engineer Job Descriptions that Attract the Best Developers” (Jennifer Fu). A fantastic quick resource, covering everything from salary ranges to SEO and Google metadata.

• This 20-minute podcast (Manager Tools) has a good walk-through of writing a job description.

• Buffer’s rationale for removing the word hacker from their job descriptions has excellent reasoning on why titles matter.

• More details from Slate on how gendered language in job descriptions can dramatically reduce the number of applicants you’ll get.

• Mitchell Pronschinske covers how to skip the buzzword soup and write more helpful job descriptions.

• The 2019 Hired Global Brand Health Report summarizes a number of ways companies can better appeal to candidates, which may help with how you describe your company in job descriptions.