Which is more important, software or the documentation that makes that software more usable and useful? Framed that way, it would be reasonable to assume both creators should make roughly the same, given similar seniority/geography/etc. Reasonable, but incorrect. Software developers may not make the fabled $3 million a year but, on balance, they tend to make a lot more than the folks writing docs that make their code approachable.
It’s time that we changed this—and not out of some hazy notion of fairness. No, you’re going to want to pay your docs writers more once you realize just how much value they create and unlock.
Panning for gold
Matt Klein knows something about the value of great developers. He’s the founder of the popular Envoy project and runs a team of developers at Lyft. Perhaps for those same reasons, though, he places an even greater premium on great documentarians or docs writers: “Finding a good technical writer is about 100x more difficult than finding a good engineer. I think they should be paid more.”
Not the same. More.
Chef Product Manager Tim Smith details why: “It really doesn’t matter what you build if no one can figure out how to use it.” Developers agree, and so routinely rank documentation as their top ask to help them be productive. Docs, says Human Security’s Bethann Noble, “are a fundamental part of product.” You don’t have good docs, you shouldn’t ship.
Even so, when GitHub polled developers on how open source projects do with documentation, 93% complained about incomplete or confusing documentation. The situation may be better for proprietary software because people are getting paid to write those docs. But the problem remains: They’re likely not getting paid enough.
According to Indeed’s salary data, the average base salary for a U.S.-based software engineer is roughly $104,000. That’s pretty close to what a U.S.-based docs professional makes, according to the Write the Docs Salary Survey 2020 data. Parity, right? Well, not when you move beyond the average. The top quartile of software developers makes a lot more than $104,000. But what about the top 25% of docs writers? Nope.
In a conversation with Datastax Chief Strategy Officer Sam Ramji, Google Technical Writer Patricia Boswell argues that great code needs a great story to frame it, to make it accessible to even the most technical audiences: “No matter how technical a topic is, the framing is always the story. You can make something more approachable by framing it as a story.” Ramji suggests that once upon a time, code was scarce and worth the bother to decipher. Now code is “abundant,” and the scarcity is in articulating a “story compelling enough that someone [will] stop what they already know and what they’re already doing to come hang out with you and check out your stuff and spend enough time developing a little bit of competence to use it and become a member of your community.”
That requires good writing. It requires good docs.
Docs become even more important when the docs, not code, are the primary interface (like, for example, a developer engaging the underlying code through an API). But a great docs writer, notes Boswell, isn’t the “kind of person who only wants to describe how [the software] works.” Instead, they’re “somebody who describes how it is used. And in order to do that, we tie all of these vision pieces together. So we create this narrative that ties the market vision and the functional vision and the user experience. We’re partnering with UX to make sure that we’re documenting the experience, and then it just flows from there.”
If that capability sounds valuable, that’s because it is. Not only are great docs writers helping others to understand why they should use software (by crafting that overarching story or narrative), but they’re helping the would-be user to situate themselves in how they’ll use the software within that overarching narrative. There’s a tactical element to all of this, but it’s a deeply strategic role.
It’s also a role that’s hard to source, according to Klein. Which means, if you want a great documentarian, you need to be prepared to pay up. Yes, perhaps even more than you pay your best developers. Without equally good docs writers, relatively few people will ever know you even employ great software engineers.
