How to Write an Effective Technical Job Description

Share this: // facebook // linkedin

Ahh, the job description. It is the face of your company on job search sites. It sets the tone for all the rest of the hiring process that follows. It has the power to make or break your hiring success. It’s a shame they’re so often badly written.

A good job description isn’t so different from a bad one. Mostly, it just has some of the letters in different places. Both types try to achieve the same goals: to describe the position and attract candidates to apply. There are a few key areas in which good job descriptions differ from bad ones:

  1. They don’t unnecessarily discriminate
  2. They don’t oversell
  3. They accurately describe the work
  4. They prepare the candidate for the hiring process

In this article, we’ll tackle each of these areas as we go through the process of writing our job description. We’ll combine all of these points elegantly into a sample job description at the end.

The job description: what is it good for?

A neon sign saying "This is the sign you've been waiting for"

As we begin, it’s important to keep in mind the intended purpose of writing our job description. We want to give potential candidates an idea of the position on offer, and we want them to feel like it’s an attractive enough offer to risk applying for it.

Applying for a position is always a risk. Candidates will be investing their time and energy for our consideration, and in most cases, all except for one applicant will be rejected. The hiring process, by necessity, is discriminatory. After all, if anyone could do the job we’re offering, we’d never bother to check whether or not someone is capable of doing it. Therefore, our job description should discriminate - but only in the areas where it’s actually necessary. Specifically, our goal is to discriminate based on competence - and only competence.

Many bad job descriptions, intentionally or not, exclude candidates for traits that have no bearing on competence. For most roles, traits that have no bearing on competence include things like age, gender, sex, nationality, ethnicity, and so on. As well, stereotypes or statistically more likely conditions that may be true for an entire country or group are sometimes unfairly applied to an individual. These are common pitfalls that unfortunately end up excluding many talented and completely capable candidates from the hiring pool. They have no place in a good job description.

Something that does have a place in a good job description is an accurate account of the critical skills needed for doing the work on offer. This usually appears somewhere after the word “required” in the text. Bad job descriptions tend to have all sorts of words in this section that describe a wish list of items that would be nice to have, but none of which are actually required for the position. This wish list often includes various degrees of higher education and advanced skills, specific years of experience, and familiarity with specific technologies or specific versions of those technologies.

It’s advantageous for us to be aware of the difference between required skills and helpful traits when we’re writing our job descriptions. While our specific position may very well require certain things like advanced study and specific technologies, this is typically the exception, rather than the rule. There’s a significant downside to misrepresenting helpful traits as requirements when this list discourages applications from capable candidates who may not fit the expected mold.

The goal when writing a good job description, then, should be to accurately relate this list of required skills. This list should include both hard skills and soft skills. If the work requires skill in collaboration, in time management, and in seeking responsibility and improvement opportunities, then these are all items we should list in addition to technical or hard skills.

After having written this list, go over each item and ask, “Could someone without this trait still competently do the work?” If the answer is yes, move that trait into the “not required but would be nice” section.

Don’t oversell it

A neon sign saying "We can be heroes just for one day"

Since the goal of a good job description is to accurately describe the position on offer (and by proxy, the company offering it), adding anything that seems to over-represent the realities of the position should be avoided. Especially for technical hires, overzealous language used to refer to technical staff is an immediate red flag. Words such as rockstars, gurus, wizards, or ninjas are indicative of a company that gives away titles more readily than appropriate salaries. It’s wording designed to appeal to the egos of developers who would make that trade. You don’t want to be that kind of company, and you don’t want to attract that kind of talent.

In the same vein, it’s pragmatic to avoid using common business buzzwords. Buzzwords tend to use up a lot of letters and time and do so without actually conveying any useful information. If a job description purports to be looking for a “rockstar developer who can make a huge impact and help 10x the development team,” any knowledgeable and effective technical candidate will recognize that sentence to be meaningless. The downside to meaningless sentences is that they make it clear that your company doesn’t have reasonable and achievable metrics for success. No knowledgeable and self-respecting technical person would want to work for a company in which their contributions are arbitrarily measured. What’s worse, if contributions are arbitrarily measured, it is entirely likely that the technical team is the company’s common scapegoat when business objectives are not achieved.

Instead of overselling the position and potentially turning off experienced candidates, a good job description will emphasize the openness of your organization. This is a great opportunity to demonstrate the openness and honesty of your culture. If your organization doesn’t pay market salaries for your area, instead let potential candidates know what your company offers to offset any perceived lack of cash benefits. If you offer childcare services or credits, remote working options, gym memberships or cell phone plans, or regular company lawn-bowling excursions, make a point of mentioning it in the job description.

Accurately describe the work

A neon sign saying "Work harder"

It may be helpful to keep in mind that our job description isn’t designed to appeal to everyone. It’s designed to appeal to people who would realistically enjoy doing the job. It then follows that if we accurately describe what doing the job will be like, the attractiveness part of our job description goals will take care of itself. With one or two sufficiently descriptive paragraphs, any potential candidate with the ability and willingness to suit the position should feel comfortable applying for it.

While it may be tempting to focus on new technologies and fancy projects, accurately describing the work also requires description of foundational technologies and practices, like writing tests and improving existing systems, should the job require those skills. We want to ensure that we manage expectations appropriately for our potential candidates, instead of dangling the proverbial carrot.

Describing the work can also encompass facts about your company culture, the makeup of your team members, or common goals and practices. Encapsulating the experience that a potential candidate may be signing up for is a great way to set expectations for all parties.

Prepare the candidate for the hiring process

This section should be straightforward and informative. If you’ve followed this series of articles from the start, you’re already familiar with the general stages of the hiring process, which we’ll simply list in this section for the candidate. If you’re not already familiar with the hiring process, you may like to read our first article.

In your description of the process, include some general timeframes and an idea of when the candidate will receive responses from your organization. This is a good opportunity to make some commitments to your potential candidates and increase their confidence in applying.

Sample job description

Below is an example job description written for a hypothetical growth-stage tech company that is looking for a software developer. Each section exemplifies one of the points we discussed above.

StartupCo is hiring developers! We are a small and diverse group of people building the next generation of VR television for cats. Since our customer base is growing, we need to add people to our team who can contribute to the continued joy of our clients (and their cats)!


We’re looking for pragmatic developers who are comfortable writing new code, tests, and improving the quality of our existing codebase. You understand the importance of automation, and you don’t shy away from taking responsibility for what you build all the way from the prototyping stage through to monitoring and supporting the systems in production. We want to work with people who share knowledge and learn from their teammates, and who collaborate well in team-based development environments. If this sounds like you, we welcome you to apply!

Helpful skills

The following traits would be welcome, but are not required:

  • Familiarity with Framework X
  • Performance analysis and profiling for Database X
  • Distributed systems infrastructure, messaging systems, infrastructure monitoring
  • Experience contributing to or managing open source software projects

What it’s like to work here

As a member of our software development team, you’ll work alongside our Product team to implement new features for our customers. You’ll also help to take care of normal housekeeping practices of writing software like adding tests, improving automation, and improving performance to help keep our operational costs low and development speed high as we scale up our traffic. We love clean code and smooth operations!

We have team members from all kinds of backgrounds! Here are some facts about our team.

  • All of us are effective developers in our domains, but only some have formal education in Computer Science. We care about your ability to produce good code more than the formal education you might (or might not) have.

  • Some of our developers came to StartupCo with knowledge of relational database query optimization and performance, but most didn’t. We practice this together as part of our regular system improvements and so far it’s really helped to increase the database knowledge of our team.

  • We think communication is important. While our official company language is English, there are people on the team from a total of 14 different countries. Since we also have some employees working remotely, we highly value written and verbal communication skills.

  • We give our team as much autonomy and trust as possible once they have demonstrated their capabilities. We make sure to provide our team members with any help needed in improving time management and prioritization skills.

  • Most of our systems are in Language X and Framework Y, but some developers started here without much (or any) experience with either. We found that after a relatively short time, people who have a solid programming background pick up the details. Our team members are dedicated to learning and improving.

Benefits of working here

As a new company, StartupCo is working hard to adjust our salaries to market rates in the X area for our developers as we grow. Our salaries are pretty competitive though, and in addition to cash benefits, we also offer additional perks:

  • We cover all healthcare insurance costs for our employees and their immediate family, including medical, vision, dental, and a complementary fitness center membership.

  • We offer a robust 401(k) program that matches all your contributions up to 8% of your annual salary.

  • We cover full short-term disability, long-term disability, and life insurance.

  • We offer remote and flexible-time working arrangements.

  • We have full childcare services on-site and an equivalent reimbursement for our remote employees.

  • We have a monthly VR games tournament and picnic for our employees and their families, including any cats.

  • Technical staff get 2 all-expense-paid conference trips per year


Our hiring process is very straightforward. Once you apply to the job posting via API (we use ApplyByAPI), we will contact you personally within 24 hours. We’ll schedule a short 20-minute phone call to chat and assess your verbal communication skills. This is not a technical screening, fear not!

If you successfully move to the next stage, you’ll be given a small 2-4 hour project in which you can demonstrate your development skills. You will be able to use the language and tooling of your choice.

Lastly, we’ll meet for one in-person interview (or video call) to discuss your project and answer any questions you have.

We are a team of great people building a really cool product for great customers. We’d love to have you join us!

Serve your applicants

An open sign

As you can see, a good job description can be a helpful and encouraging way to get interested and suitable candidates to apply for your position. By being clear about required skills and helpful skills, accurately describing the work without overselling it, and being transparent about your company and hiring process, your job description will provide a great starting point for finding your next ideal technical hire.

In addition to an attractive job description, using a top-of-the-funnel screening tool can help immediately qualify applicants, and also provide a fun way for talented candidates to apply. You can read about the benefits of filtering for better tech hiring in my previous article. You might also want to learn more about ApplyByAPI, the automated way to screen candidates for technical competency and hire better developers.