Should documentation writers get paid more than developers?

3 years ago 370

Commentary: Given the importance of documentation to making software usable, should documentarians earn a bigger paycheck than developers?

Without great documentation, great code...isn't. Great documentation, after all, makes code more approachable, more useful. Bad code? Well, as The Taproom CEO Kelly Vaughn tweeted, "Please, please, PLEASE–I am begging you–invest time and resources into your documentation. I've been running in circles for 3 days now trying to solve the same problem because the documentation is terribly lacking."

In fact, if you ask developers their most desired support for being productive with software, as SlashData did, it's documentation. Nothing else comes close.

And yet, it's not clear that companies value their documentation writers accordingly. Or perhaps the problem is that documentation writers don't value themselves as much as they ought. RedMonk's KellyAnn Fitzpatrick has a great analysis of the Write the Docs Salary Survey 2020. But for me, the biggest takeaway that is implied but never stated: few, including the doc writers themselves, may value documentation highly enough.

"Docs or you don't ship it"

When I managed Adobe's Developer Ecosystem team, we tried to institute a few central tenets. One was that product teams should invest more heavily in the open source communities upon which they increasingly depended. A second was that product teams should default to public, not private, APIs. Implicit in this second tenet was a belief that if a team knew its API would be public, it would do a better job creating and documenting the API.

SEE: How to build a successful developer career (free PDF) (TechRepublic)

I believed then, as I believe now, that docs are critical to software (and API) adoption. Hence, I agree with former Twitter documentarian Troy Howard who declared: "Docs or you don't ship it." Documentation, in other words, isn't ancillary to the product: it is an integral part of the product.

It's not surprising, therefore, that developers cite documentation as the most important thing a software provider can offer them, well above other important options like training, development tools, etc. (Figure A).

Figure A

Great technical writers don't merely write, as important as that is. According to Fitzpatrick, "[T]he skill of being able to string words together per se is not enough to ensure the production of great technical documentation." You need to invest time in research, parsing the expertise of subject matter experts and more. Writing is important, but knowing what to write and how to explain it, is just as important.

SEE: Hiring kit: Technical writer (TechRepublic Premium)

Sounds hard, right? Sounds important, too. Given how important software has become to the functioning of business and society, you'd think we'd pay a hefty premium for people who can make software useful for a broader audience than it might otherwise reach.

Well, maybe we do.

Getting paid

If you look at Indeed's salary data, the average base salary for a U.S.-based software engineer is approximately $104,100, plus another $4,000 cash bonus per year. If accurate, that's roughly in-line with what a U.S.-based documentation writer makes, according to the Write the Docs Salary Survey 2020 data (Figure B).

Figure B

(A quick spot check against Glassdoor and other data sources for software engineers suggests the same rough parity exists for other countries.)

I'd call that a victory. Right? If a software developer is going to make $100,000, shouldn't the documentarian make roughly the same, given that she will be just as important to the software's success?

Most Write the Docs Salary Survey respondents (72%) seem to think so, saying they're "satisfied" with their compensation. But should they be? For the 10.7% of respondents who say they're "unsatisfied" with their pay, their top reason is "Pay is too low." And for those relative few who are "unsatisfied" with their jobs, the top reason (cited by 46%) is "Role is undervalued or underfunded."

Perhaps it's the writer in me, Oliver Twist-style, asking, "Please Sir, I want some more." And maybe more isn't needed. Maybe documentarians make enough. Yet software engineers keep getting paid more, and the top 25% of developers make considerably more than that $104,000 average. I don't have the data, but I'll hazard a guess that the best documentarians don't get anywhere near the salaries of the best engineers, despite having significant, if not equivalent, impact.

I'd love to hear your take. Do you think good documentation writers should get paid the same or more than good software engineers? Why or why not? Talk to me on Twitter or in the comments below.

Disclosure: I work for AWS, but the views expressed herein are mine.