The extreme importance of software documentation

What is more important, the software or the documentation that makes this software more usable and useful? Framed this way, it would be reasonable to assume that both creators would have to do roughly the same, given seniority / geography / etc. Reasonable, but incorrect. Software developers may not make the legendary $ 3 million a year, but overall they tend to make a lot more than people who write documents that make their code accessible.

It is time we changed that, not out of a fuzzy notion of fairness. No, you’re going to want to pay your document writers more once you realize how much value they create and unlock.

Gold panning

Matt Klein knows something about the value of great developers. He is the founder of the popular Envoy project and leads a team of developers at Lyft. Perhaps for these same reasons, however, he grants an even higher premium on major documentary filmmakers or docs editors: “Finding a good technical writer is about 100 times more difficult than finding a good engineer. I think they should be paid more.

Not the same. Following.

Product manager product manager Tim Smith Details why: “It doesn’t matter what you build if no one knows how to use it. »The developers agree, and therefore regularly filing documentation like their top ask to help them be productive. Documents, says Bethann Noble of Human Security, “are a fundamental part of the product.” You don’t have good documents, you shouldn’t ship.

Even so, when Developers interviewed by GitHub Of how open source projects deal with documentation, 93% complained about incomplete or confusing documentation. The situation may be better for proprietary software because people get paid to write these documents. But the problem remains: they are probably not paid enough.

According to Indeed salary data, the average base salary for a US-based software engineer is around $ 104,000. That’s pretty close to what a US-based documentation professional does, according to the Write the salary survey Docs 2020 The data. Parity, right? Well, not when you are above average. The top quartile of software developers do a lot more over $ 104,000. But what about the top 25% of document writers? Nope.

In a conversation with Sam Ramji, Chief Strategy Officer of Datastax, Technical Writer at Google Patricia Boswell argues that good code needs a big story to frame it, make it accessible even to the most technical audiences: “No matter how technical a subject is, the frame is always history. You can make something more accessible by presenting it as a story. Ramji suggests that once upon a time the code was rare and worth deciphering. Now the code is “plentiful” and the scarcity is in articulating a “story compelling enough that someone [will] stop what they already know and what they are already doing to come spend time with you and check your stuff and spend enough time developing a bit of skill to use it and become a part of your community.

It takes good writing. It requires a good doc.

Documents become even more important when documents, not code, are the primary interface (like, say, a developer engaging the underlying code through an API). But a great documentary writer, Boswell notes, is not the “kind of person who just wants to describe how [the software] works. ”Instead, they’re“ someone who describes how it’s used. And to do that, we tie all of these pieces of vision together. So we create this narrative that ties together market vision and functional vision. and user experience. We partner with UX to ensure that we document the experience, and that it flows from there. “

If this ability sounds valuable, it’s because it is. Not only great document writers help others understand Why they should be using software (in creating this overall story or narrative), but they help the potential user to situate themselves in how they will use the software in this overall narrative. There is a tactical element to all of this, but it is a deeply strategic role.

It’s also a difficult role to find, according to Klein. Which means if you want a good documentary maker, you have to be prepared to pay. Yes, maybe even more than what you pay your top developers. Without such good document writers, relatively few people will know that you employ even great software engineers.

Copyright © 2021 IDG Communications, Inc.

Sam D. Gomez