Search results

Podcast with Andrew Davis: Hiring API doc writers -- an inside look at fixing broken processes

by Tom Johnson on Feb 23, 2020
categories: api-doc podcaststechnical-writing

I recently chatted with Andrew Davis, a recruiter for API documentation positions in the San Francisco Bay area, about why it's so difficult to hire technical writers for developer documentation roles. Andrew has more experience and knowledge with developer doc jobs, companies, and recruiting processes than nearly anyone else in the tech comm industry. He actually helped me find my first dev doc job when I transitioned to California years ago. Andrew's company is called Synergistech Communications. In this interview, Andrew provides an inside look at fixing broken processes around hiring.


Listen here:

High-level summary

Here are some of the topics we cover:

  • Why some job descriptions seeking unicorn candidates are unrealistic and insincere
  • How recruiters, sourcers, and managed service providers work against the hiring process
  • How to avoid getting spammed on Linkedin by keyword sourcers
  • Whether a high hiring bar actually reflects good faith efforts for hiring
  • How to assess whether candidates are worthwhile without too much investment of time
  • How to use Linkedin productively to evaluate candidates
  • How candidates can get around NDAs or private docs to provide writing samples
  • Whether desperation in the hiring team can bias judgment of candidates in the interview process
  • Whether hosting meetups or other community events translates into better candidate applications

Detailed notes

Before the interview, I provided Andrew with a list of possible questions. He prepared some detailed notes. The following isn’t a transcript of the podcast, but it gives a good idea of what we talk about. The podcast itself is more dynamic and direction-changing, while these written responses are more readable and informative if you’re not listening to the podcast.

Tom: (Q1) For companies trying to hire candidates for dev-doc roles, the positions often seek out unicorn candidates in terms of tech knowledge and writing experience. Are companies often surprised when they can’t find tech writers who have the exact specialized tech knowledge they want and advanced writing skills and publishing toolchain experience and API/SDK experience and project leadership experience?

Andrew: I agree that companies appear to be raising the bar for tech writers’ tech knowledge and writing experience.

Are they surprised their Goldilocks, committee-generated job ads aren’t resulting in qualified applicants? I sincerely doubt it. If they are surprised, it’s because they don’t understand how rare these people are, much less how they prefer to work. Tone-deaf demands tend to backfire in a candidate’s job market.

If they were serious about filling these posts, and finding people who both can and want to do the work, they’d engage with those who have done it but prefer, say, to work on contract or remotely. In most cases companies won’t even try. Call me cynical, but this suggests to me that management isn’t serious about hiring and, frankly, that the posted positions aren’t actually funded but are more of a resume-harvesting maneuver. If I’m right, the only thing that will motivate management to get serious is when their existing resources start pushing back or, worse, defecting.

When I recruit for a company that seeks unrealistic combinations of skills and experience, I ask 1) have you ever met someone like that? and 2) do you have any idea what such a person would cost? Invariably the answer to both questions is “no”.

I inform them that their particular purple squirrel probably does exist somewhere but costs a lot more than they can afford. We then start prioritizing. How important, really, is it that the person work onsite? Or have experience with the company’s unique toolchain? Or work as a salaried employee? Or manage others? Essentially I’m asking: do they want the work done, or do they want to boast about the caliber of talent to which they can dictate terms? Most hiring managers laugh nervously and then get pragmatic. A day later, the company is looking at a couple resumes of very qualified people who long ago took down their LinkedIn profiles and now only work through word-of-mouth referrals from trusted associates.

So, are companies surprised that they can’t attract this talent with their current strategies? Probably not. Are they willing to try more audience-aware, nuanced approaches? In most cases, not yet.

Tom: (Q2)How does the hiring process between engineers and tech writers differ? It seems like many engineers must pass rigid technical tests to validate their experience. Are those same tests applicable and relevant to hiring dev-doc tech writers, or does that process over-index on the tech side?

Andrew: The latter.

I don’t recruit engineers, but my understanding is that engineers must pass demanding technical interviews, with right-or-wrong answers, over the phone or on videoconference calls before they’re ever invited to interview in person.

Most dev-doc technical writers don’t have to clear the testing hurdle, although I’m aware that Google typically demands them. That’s not to say that technical writers aren’t evaluated for their technical acumen, just that it usually happens later in the process and that the engineer asking the questions has lower expectations for accuracy and completeness. I seldom hear of otherwise qualified technical writers being rejected solely because they answered a technical interview question incorrectly.

As I understand it, the hiring process for technical writers also differs from that for engineers in another way, namely that the candidates for dev-doc roles interview with a wider range of departments. It’s not unusual for candidates to be evaluated by Engineering, Marketing, Technical Support, and Product Management in addition to the Documentation team. In small companies an executive will often get involved, and in larger ones UX and QA teams might participate. If everyone had closely aligned agendas and scorecards, this might yield great results. In practice, though, different groups’ expectations and standards are in conflict, so there’s no unanimity from these committees and the candidate is usually rejected.

In my opinion, what’s needed is for the candidate’s would-be direct manager to have veto power over one or more interviewers’ ‘no’ vote. Is this the case in most companies? No.

Tom: (Q3) Many companies are locked into recruiting agencies to find and hire tech writers, when these recruiters know very little about what tech writers even do. Are these types of “blind” recruiters, who likely recruit for many different kinds of tech and engineering positions that they are also unfamiliar with, faced with an uphill battle in finding the right candidates, especially when the job description mandates knowledge of X, Y, Z skills?

Andrew: Yes. Recruiting without access to the hiring manager is the archetypical uphill battle. Recruiting in a vacuum for a hybrid laundry list of skills, most of which are associated with much higher-status and better-paid professionals than tech writers, is doubly difficult. (Gosh, did I just insinuate that people with the target skills might not want to work as a tech writer? Hmmm.)

To explore your question a bit further, you used the phrase “locked into” regarding companies’ relationships with recruiting agencies. Most people don’t realize how that dynamic works, and how uneven the playing field actually is.

Essentially, mid-size and larger companies often engage a Managed Services Provider (or MSP) to direct their staff and contractor recruiting activities, and specifically to keep the company tax-law compliant. The MSP subcontracts the task of sourcing candidates for its client to generalist IT recruiters and ‘professional services’ or ‘consulting’ companies, with the selection criteria being breadth of scope and, of course, price.

Those IT sourcing services then get a single chance to participate in a conference call with the hiring manager — usually just a rehearsed reading of the job description — and then they race to present candidates. They’re evaluated by volume and speed.

Because of these sourcers’ lack of understanding and their unwillingness or inability to get nuanced answers in such a public forum, the process of finding candidates has devolved into a Boolean keyword search, broadcast emails, and incoherent sales calls. That’s why your phone rings at all hours of the day and night with thickly-accented salesfolk offering you “a perfect opportunity” that’s only two states away and pays half what you need to earn. It’s also why these callers’ first question is often “what is your hourly rate?” As a result, employers’ applicant tracking systems are swamped with poorly scrutinized applications that fit the sourcing company’s “pricing profile” but are otherwise off-target.

(To my knowledge, the exceptions to the ‘MSP-in-control’ model include Salesforce, Google (but only for staff positions), Amazon, Oracle, and Splunk. These companies all have internal recruiting teams that actually know their craft and interact effectively with hiring teams.)

What’s significant about the MSP model, especially for my company, is that MSPs deliberately exclude narrowly focused independent recruiters who know their market niche — and especially their candidates — much better than the volume- and transaction-oriented generalist IT agencies. As you’ve pointed out, the generalists make no attempt to understand what tech writers actually do or care about, even if they have the courtesy to ask.

As an independent recruiter focused exclusively on technical content development, primarily in the San Francisco Bay Area, my business model is to cultivate relationships with technical writers and their managers, to advise and support them, and to stay current with industry trends. Ultimately I benefit when those professionals hire, or influence hiring decisions, and want quick, well-vetted results, candid input, and three decades of experience with software documentation.

The issue is that MSPs appear to perceive me as a threat. After being introduced as a willing, proven staffing provider by the publications manager or director, MSPs have rejected me as a potential vendor for such reasons as a) not having more than three employees, b) not carrying commercial auto insurance (because my company doesn’t own any vehicles nor do I transport my clients’ people or products), and c) not putting my clients’ contractors on my own payroll. Sometimes they just tell me “it’s too difficult to add another vendor to our list.” Go figure.

I hope the pendulum swings back toward sharp-shooters and away from shotgun artists. In the meantime, I work primarily with startups, where MSPs fear to tread because they know their promises will get them laughed out of the room.

Tom: (Q4) How exactly do recruiters go about finding candidates? I feel like I get approached on LinkedIn at least every day by a recruiter for a different position. Often the recruiter will say that my profile is a great fit for the position, and when I ask for more details, the job involves something that isn’t a good fit. For example, converting legacy documents into Microsoft Word and Visio, or something. How are these recruiters matching positions with candidates? And how can candidates adjust their LinkedIn profiles for a better matching experience?

Andrew: Recruiters, or rather ‘sourcers’ in this case, are hunting for keywords. I’ve explained (in my answer to Q3) how sourcers are engaged by companies’ MSPs. A sourcer’s priorities are speed, volume, and economy. Notice I didn’t include “accuracy” in that list. So the people contacting you aren’t really recruiters who can elucidate and persuade, as much as data-processing minions tasked with dragnet trawling and getting your attention.

It’s important to understand that sourcing ‘services’ don’t actually read resumes. That’s especially true of your LinkedIn profile’s Summary statement (where you probably indicate the kind of work you seek). Sourcers perform Boolean searches on LinkedIn and resume databases then solicit your ‘right to represent.’ If you grant it, a real recruiter will often get involved and you can expect a slightly more informed email or call with additional details and, possibly, answers to your questions.

You asked how to adjust your LinkedIn profile for a better matching experience. Given that profiles aren’t usually read by MSP-contracted humans, just searched by a computer, you could try including only those keywords (tools, technologies, industry niches, programming languages, etc) you would actually want to use in a future role. I’d hope that MS Word and Visio would fall off your list under those circumstances.

You could also try supplying dummy contact information in your LinkedIn profile, sending all LinkedIn-related inquiries into a ‘holding’ email box and all unrecognized calls to voicemail.

If that fails, tell the caller that you know someone at their client company and will be applying directly, but “thanks for the tip!” Trust me, they won’t like hearing that and definitely won’t call you back.

Tom: (Q5) Is there much value in the professional connections on LinkedIn when people have thousands of connections with people they don’t even know? I often accept all connections (filtering out recruiters or HR groups) because then when I post on LinkedIn, they’ll see the posts in their feed. But perhaps I’m not using LinkedIn as I should.

Andrew: Looking at your LinkedIn feed, it’s clear you make better use of LinkedIn than most. You have taken seriously the social element, circulating relevant information to a community that values having a central source of such content.

I doubt most of your non-tech-comm connections care about the content you post, like, and share, but they do benefit from having a wider circle of potential contacts to whom they can introduce themselves by saying “we both know Tom Johnson.” Although you might not know it, by accepting their connection requests you’ve become a gateway to others’ networking efforts. For those few who actually know how to use LinkedIn to leverage mutual connections, you’re a god-send.

I use LinkedIn differently. I exclude people who aren’t current or aspiring technical communicators because I don’t want to give free access to the technical communications talent I know. I reply to all LinkedIn connection requests, explaining what I do and why I’ve accepted or rejected their invitation. When I tell the latter that I reserve my network for working technical communicators but would be happy to help them find one for their team, or even to transition to our business, I usually get silence or “sorry, you’re right, my invitation was off-target” (which I take as shorthand for “I was hoping to milk your network”).

Tom: (Q6) We’ve struggled to find candidates to fill positions at my company, and it can take months, even years, to hire a single person who meets the hiring bar. In this case, Amazon wants candidates to raise the bar by being 50% better than the average person in this role at the company. Since you recruit candidates, you have a spiderman-like sense of who is legit and who is someone to pass on. When I look through resumes, how can I tell if the candidate is worthwhile? I’ve tried analyzing writing samples, but many candidates fail on passing other parts of the interview, such as articulating their experience related to the leadership principles.

Andrew: I clearly don’t think like Jeff Bezos, but from the perspective of someone who knows plenty of people who could — and would like to — help Amazon, I think demanding that newcomers raise the bar by being 50% better than your existing (above-average) team is a self-defeating exercise.

It reminds me of being told, the month after I joined Oracle as an army-of-one tech writer in 1988 (documenting their database on proprietary minicomputer platforms), “now go find someone who knows everything we’ve just taught you and who’ll work for less (than the $26k they were paying).” I can only guess that you personally are the casualty of this flawed logic and that you’re working longer and accomplishing more than most, and earning substantially less than you’re worth. This is exactly why tech companies don’t boast about retention; they don’t even try to keep you from frying.

If we were in a recession and there were indebted, overqualified tech writers on every street corner like there were in 2002 and 2008, I’d say Bravo! (It’s cruel, but that’s capitalism for you.) But we’re in a next-to-zero-unemployment tech economy where salaries are rising quickly and technical writers with the skills Amazon wants have an unprecedented range of professional opportunities as well as work-styles available to them.

You asked how to tell if a candidate is worthwhile. I’ll summarize how I do it, but we must first agree that there’s a difference between ‘being worthwhile’ and being able to pass muster in a conflicted, consensus-averse interviewing context.

By the way, how much practice does it take to articulate one’s experience ‘related to Amazon’s leadership principles’ while keeping a straight face? High-EQ professionals, especially technical communicators, probably have a hard time there.

Those implicit conflicts aside:

  1. I start by scouring the candidate’s resume for evidence that they write and organize content well and can understand my client’s technology and audience (or a similarly sophisticated one).
  2. I look for evidence that they’ve actively upgraded their skills, even if they’ve not yet used the new ones in the workplace.
  3. I then study their writing samples, preferably ones they’ve written and delivered solo, looking for clarity, precision, and consistency.
  4. If the person is still in contention, I speak with them by phone or in person at an STC or Write the Docs meetup.
  5. If all continues on-track, I use my network to do a back-channel reference check, asking former colleagues (but never their references) “what is this person really like?” and “what else should I know?” before risking my reputation by representing them. If I find inconsistencies, I dig deeper.
  6. If I find non-fatal flaws, I note them in my cover letter to my client. Everyone’s human, but with this research I get a good idea of whether the candidate is a client-compatible one.

Tom: (Q7) What would you recommend as the ideal hiring process? Would you start with a phone screen, then analyze writing samples, then do an on-site interview? Is there a better way to vet candidates?

Andrew: I’ve just outlined how I evaluate technical communications candidates (in Q6), but find that most clients don’t want to do that legwork.

What’s essential is to have a fellow technical communicator (preferably the person who’ll manage the candidate, but a tech writer friend or former colleague will do) study the person’s resume and ‘fully owned’ writing samples. This won’t prove compatibility or the opposite, but it should help generate a list of questions that non-technical communicators can ask (about specific technology, systems, tools, processes, even corporate culture compatibility).

Don’t involve anyone else on the team until the resume and samples have been evaluated against the role’s priorities. Then have a phone conversation with the candidate to ask some of the top-priority questions from the list. The employee making the call should understand the role, its context, and the audience; putting someone without this background on the phone with a talented, in-demand candidate is the quickest way to alienate them.

If the phone interview goes well and the candidate is interested, move quickly to an in-person or videoconference-style interview. Make the candidate aware in advance of the people (names, titles) who will conduct the interview, as well as what they’ll focus on. Don’t have more than one person ask the same question; it makes the hiring team look disorganized or, worse, devious.

After the in-person interview, interviewers should confer immediately and deliver their verdict via the intended hiring manager. Silence, or generic “we’ve decided to pursue other candidates” emails, are frustrating and unlikely to lead to constructive outcomes. Best case, express enthusiastic gratitude for their interest and engagement, deliver the verdict, explain where the concerns were (if the answer is ‘no’) or why you think this person’s great (if it’s ‘yes’), and either ask for a referral to someone they think would be a better fit or discuss compensation and a start date. Even if you really want to hire this person, waiting too long to say so is a bad idea.

Tom: (Q8) Most candidates need to provide writing portfolios in the job-selection process, but sometimes the writing is behind a firewall. Can you recommend any strategies for this situation? Is it a red flag to show an employee some writing that isn’t public? If you have this writing uploaded on your private site (behind a login), does that set off alarm bells in employers’ minds?

Andrew: I recommend that candidates seek past employers’ and clients’ permission to share variants of the content they created. No, not the actual published content, but a neutered version that changes product names, command-line content, and so forth. They should seek approval for sharing that content from Legal or Engineering (or both) before sharing it with future employers or clients. Since they have most leverage before they accept an offer, I often suggest candidates seek this permission as a condition of employment (subject to case-by-case evaluation later) and get it in writing as part of their offer letter.

I also recommend candidates share only brief extracts from longer documents, and perhaps tables of contents, sufficient to convince hiring teams that the person can create the kind of content needed (for example, conceptual, procedural, reference, tutorial, and so forth).

Another solution that I’ve seen work is to create a brief NDA (non-disclosure agreement) that protects both the candidate and the past employer or client, asking for a signature and email address from anyone who sees the shared (but always neutered) content. The candidate can then share that ‘mini-NDA’ and associated names with their past employer or client as evidence that they sought to protect their content while also demonstrating ownership.

Regardless, I like to see portfolio samples be password-protected, and (as much as possible) file downloads be prevented. Change that password within a week of sharing access; it’ll keep the hiring team on their toes and respectful of the candidate’s situation.

Tom: (Q9) Is there value in a company hosting meetups and other events to promote an image of fun, friendly, positive work environment for that role? For example, LinkedIn recently hosted a WTD meetup at their downtown location. Does this really work for recruiting candidates?

Andrew: If a company’s culture is a selling point to the targeted candidate, it can’t hurt to host meetups and make employees available for Q&A sessions.

Bear in mind, though, that technical writers are atypical of most tech industry hires; they’re frequently more introverted, skeptical, and emotionally intelligent than the engineers that tech companies drool over. If a company boasts about its on-campus frills and playful culture, most experienced technical writers will be turned off. They’d prefer an actual cubicle (or a well-defined work-from-home schedule), motivated SMEs, and a manager who protects them from office politics to any amount of Millennial-oriented “fluff.”

In my experience, in-demand dev-doc tech writers are usually in their 50s and 60s. They want to be left alone to concentrate, given chances to do superior work in collaboration with smart, motivated colleagues, and be recognized for making a difference.

Sometimes it seems to me that Silicon Valley companies try too hard to impress with their toys and how hard they play. By contrast, they evade any commitment to workers’ professional development and the kind of work/life balance that a Boomer or Gen-X’er would actually care about.

Contact information

Contact information for Andrew:

Andrew Davis
Synergistech Communications
[email protected]

Other links and resources:

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.