Recently social media has generated a number of excellent takes on the importance of good technical documentation. First, there’s the (spot-on) argument that documentation should be considered part of the product.
#WriteTheDocs. Docs are part of the product.
— Carolyn Shannon (@chicagomom) June 20, 2021
And then there’s the phrase “Docs or it didn’t happen.”
Docs or it didn't happen.
Docs or people will end up wasting countless hours of their lives to figure out some triviality and hate your product for it.
— Troy Howard (@thoward37) June 14, 2021
And on to my favorite, courtesy of Brigid Johnson at AWS: “Docs are like gold.”
Overheard in AWS – "docs are like gold" pic.twitter.com/TSrbsxswhu
— Brigid Johnson (@bjohnso5y) June 16, 2021
On a related note, we’ve also seen a lot of companies–especially those that are engineering-centric companies like Spotify, and/or companies that produce tech used to build other tech– looking to hire roles related to technical writing and documentation. Just to name a few (with the caveat that job posting links are ephemeral):
- GitHub is looking to fill positions such as Senior Software Engineer for its Octoservices team, which handles “the full stack of features and technologies that power Admin Experiences, Audit Logs, Migration, Learning Lab, Docs, and more tools and services that enable our millions of customers to use GitHub, increasing the impact of software solutions at a global scale.”
- Google not only appears to be perpetually hiring tech writers, but also has a nice set of instructions on how to become one.
- HashiCorp is hiring a Technical Product Manager, Practitioner Experience, where a successful hire will “Drive the development of a meaningful and intuitive practitioner experience across our project websites and documentation sites, focusing on our audiences that include developers, operators, systems administrators, etc.” (n.b., I love the term “practitioner experience” here).
- Red Hat is looking for tech writers for everything from Middleware Runtimes to Managed Services.
- Spotify is looking for a UX Writer for its Platform team “to create and maintain unified design language standards, guidelines, and other resources required for a cohesive and scalable user experience across mobile, speakers, and other devices.”
- Twilio—a company that RedMonk often cites for its exemplary technical documentation—is looking for writing-based roles including Content designer and Staff technical writers, the latter of which is introduced as:
The person in this role will assist in all aspects related to internal documentation, from the research and strategy phase to execution to ongoing maintenance of our supporting processes and docs.
Responsibilities can include anything from assisting in user research interviews to helping research content management solutions, but the daily tasks will relate to delivering internal documentation to support the R&D department. This position is for an individual who can comfortably tackle long-term, complex technical writing projects in a self-directed manner. You should be as skilled at collaborating closely with SMEs and obtaining key information as you are with efficiently compiling that information and translating it into a language and format tailored to your specific audience(s). Reporting to the R&D Enablement team, this position plays a key role in building Twilio’s internal knowledge base.
And this is just a tiny sampling.
For folks who understand the value of great documentation and the people who produce it, and who are looking to invest in hiring and retaining tech writing talent, I suggest taking a look at the recently published results of the 2020 Write the Docs Salary Survey.
Write the Docs (WTD) describes itself as “a global community of people who care about documentation.” In addition to salary surveys, the group–which does not charge a membership fee–organizes conferences, meetups, a Slack workspace, and a jobs board. WTD states the purpose of the 2020 Salary Survey as follows:
Our goal is to help people understand the pay scales and benefits in the software industry around documentation. This will help people get a better understanding of what an appropriate salary is, and then negotiate for a better one.
In publishing the 2020 Salary Survey results last month the group further noted that
We loved seeing our community use the previous results to set expectations for wages, benefits, and overall relationship with work.
We're excited (and a bit relieved) to share our 2020 Salary Survey results. We loved seeing our community use the previous results to set expectations for wages, benefits, and overall relationship with work. 💓https://t.co/zBjm7U2SlJ pic.twitter.com/bv5h7Nj50S
— Write the Docs (@writethedocs) June 15, 2021
2020 is only the second year that WTD has conducted its salary survey after running its first in 2019. While this means that the salary data is not as long-ranging as, say, the salary database available through the Society for Technical Communication (STC), the advantages of the WTD survey for teams looking to hire a tech writer (especially in software-related industries) are as follows:
- WTD survey results are freely and publicly available (where as the STC database is available to paid members or for an access fee).
- The WTD community (and the majority of survey respondents) skews toward practitioners focused on software development and technology-related fields.
- Based on the changes between the 2019 and 2020 surveys, WTD sees the survey per se as a work in progress, adapting to meet community suggestions and world events (such as the COVID-19 pandemic).
While I invite you to check out the full WTD Salary Survey 2020 results for yourself, I also offer the following as my top takeaways for folks looking to hire for tech writing related roles.
Not all folks who produce docs have tech writer titles
As noted in the sampling of job postings I list above, not all positions centered on producing documentation and other forms of technical communication (e.g., UX copy, knowledge bases, style guides) have “tech writer” in the title. One of the things that I love about the WTD community is that they embrace the term “documentarians” as a way to include practitioners who contribute to documentation but who may hold other job titles. And while survey results indicate that many respondents do have some form of “tech writer” in their official job titles, the variety of Job Title responses submitted offers insight into the different titles used. This variety can prove useful when articulating specific job postings and positions, but also in understanding the backgrounds of potential candidates.
Also of interest: responses to the Type of Role questions, which break out how respondents see themselves functioning within their organization. While the majority of respondents went with the “writer, content creator, producer, or editor” option, other responses included “manager,” “developer,” “educator,” and “advocate.”
Tech writers/documentarians do more than “wordsmith”
One of the more interesting sections of the survey juxtaposes responses for Proportion of role officially related to documentation to those for Proportion of role actually related to documentation. There is a lot to glean from this regarding roles where folks take on documentation tasks unofficially (and I have certainly been there), as well as the potential disconnect between time expected to be dedicated to documentation and time that actually is. Part of this, of course, may simply be the usual workplace overhead that many of us experience: time answering email, sitting in meetings, or trying to get our various video conferencing software to work. And yet, I suspect this may also result from varying definitions of what counts as a “documentation-related” task.
Writing, for instance, is often recognized as the most clear-cut documentation-related task. However, as noted in the sampling of job postings listed above, tech writing/documentarian positions often go beyond simply writing documentation, including tasks such as user research, collaborating with SMEs, establishing user pathways among existing collateral, and even establishing documentation pipelines.
Even within the task of writing, the skill of being able to string words together per se is not enough to ensure the production of great technical documentation. A few weeks ago I chatted with Andy Stevens, Technical Content Manager at Linode, about his advice on Hiring and Tech writers. One of his key suggestions:
I think if you’re looking to hire a technical writer, I think one of the biggest challenges is finding someone who brings something more than just writing proficiency to the job.
Other key components we discussed as essential to great documentation include empathy and attention to the audience. However, it also became clear that as documentation processes evolve to align with those used in software development per se, documentarians are also expected to understand things like git, docs-as-code systems, automated testing tools, and static site generators.
In other words, when creating and hiring for a tech writing role, it is important to understand and seek out all of the skills that go into producing and maintaining great documentation. And while writing skills are important, the work of creating documentation should never be reduced to just writing (or, as a former colleague would call it when they really wanted to frame the technical writing I did as completely devoid of any actual technical component, “just wordsmithing”).
Pay your tech writers/documentarians well
The Salary section of the survey provides regionally-specific median salary information for respondents. Given the pool size, this may be an area where other surveys and hiring tools prove more useful in gauging salary range. However, this section also provides information on other benefits, as well as various salary and job satisfaction information (I suggest that you get familiar with this section, because we are going to comb through it for the next few takeaways).
Among respondents who were not satisfied with their salary, the #1 reason given was “salary is too low”; it is also worth noting that among respondents who noted that they were not satisfied with their job (vs. with their salary), the #1 reason given was “Role is undervalued or underfunded.” I would love to see a separation between “undervalued” and “underfunded” in the potential survey response options (and per my takeaways list, I have clearly separated the two, even though they are arguably related). But here the point I want to stress is that it takes a lot of skills to produce great documentation, employers should expect to pay for those skills accordingly, but not all employers do. Often this results in tech writers/documentarians changing employers in order to access the compensation and benefits that are commensurate with their skills (and those required of their job); others opt for moving into other parts of an organization, often into more engineering-based roles that make use of some of the SME knowledge they have acquired while documenting all the things.
One way to prevent this churn: pay your tech writers/documentarians what they are worth. And then pay them more to make up for the fact that your org may be one among many that undervalues their worth.
Value your tech writers/documentarians (and hire more of them)
Returning to the # 1 reason cited for job dissatisfaction among respondents: “Role is undervalued or underfunded,” I’d like to focus on the undervalued part. While recognition of value is often tied to salary, it can also manifest in other areas: reasonable promotion paths (also an issue noted in survey responses), recognition of the work itself as valuable, recognition of expertise per se as valuable. If you have nine levels of job titles and a plethora of internal recognition mechanisms for software engineers but zero advancement paths or accolades for the folks who specialize in creating your documentation, it may be difficult to keep any tech writers/documentarians you do hire.
Another related way to recognize value (that perhaps gets at the intersection of respondents feeling undervalued and underfunded): appropriate funding for the work required. This can manifest as funding for tools and training (and “outdated toolsets” is another reason cited for job dissatisfaction in the survey), hours allocated to actual documentation projects, and headcount devoted to actual documentation tasks and the gluework that often goes with them.
The headcount part can be especially telling (and while the survey does ask whether respondents work solo or on (a) team(s), teams mean only that they work with other colleagues, not that those colleagues are necessarily also working on documentation). Often teams or organizations will budget to hire one tech writer when the work expected is more than three could reasonably accomplish. Documentarians who have found themselves in such a situation can be wary of joining teams or organizations where they are the only tech writer, or where tech writing is a casual “add on” to another role. If all the public facing documentation for your organization is generated by a single QA analyst in the “spare” time created via a 100-hour work week, folks may conclude that your org does not value documentation or documentarians (and fixing that will probably take more than one tech writer/documentarian hire).
Conversely, willingness to invest in multiple documentation roles can be read not only as dedication to great documentation, but also as a larger organizational recognition of value in tech writers and their expertise. (Side note: it also creates potential collaboration and mentoring opportunities, which makes hiring and nurturing less experienced applicants a more feasible option). And so one way to hire (and retain) better tech writers may be to prioritize hiring more of them.
Consider the 2020 WTD Salary Survey results as only one of the tools/points of information available to anyone looking to hire a tech writer, but one that has a very precise respondent base and is reactive to evolving industry conditions. And while the survey is positioned primarily to help documentarians better understand and negotiate salary and working conditions, it also has a lot to tell us about how employers can shape job postings and actual tech writing-related positions to attract and retain tech writing talent.
Or, if you want an even more summative and succinct directive, I offer this take from the excellent Stephanie Morillo:
Hire more technical writers, and pay them **well**. The salaries of many technical writers fail to reflect the value technical writers deliver and how HARD their jobs are. Technical writing is a skill that requires time and practice to master. https://t.co/0ZyKuse8ro
— Stephanie Morillo (@radiomorillo) February 4, 2021
Disclosure: AWS, GitHub, Google Cloud, HashiCorp, Red Hat, and Twilio are RedMonk clients.