[bobwaycott]

Some years ago, I spent a time being such a docs expert. I was documenting an SDK for iOS and Android, so dealt with Obj-C and Java simultaneously. I had to converse a lot with the dev team to understand their thinking behind choices. What I didn’t expect—and somewhat stumbled into by accident—was that I essentially became the person who spotted the myriad ways in which the iOS and Android teams didn’t communicate or plan SDK features and interfaces together, and wound up guiding SDK development from a docs perspective. Each platform was nothing like the other. I recall a lot of long conversations wherein I exhaustively explained why class and function names (as well as results!) should match across both platforms. And it took way more time than I thought it should—but I remember the light bulb moment when both the iOS team and Android team jointly realized there were devs out there who might want to build for both platforms, and would be frustrated if they had to learn the SDK twice. I became in that moment not just the guy who was writing all the developer docs, but the de facto lead for architecting and organizing the SDK itself, helping both teams plan together and create a consistent product. To me, it was second nature. To the other devs, they just didn’t think that way, and it took a lot for them to see the value (and let’s just ignore people who think code documents itself).

I share all that to say that I’m not sure it’s as easy to teach devs how to write good docs and continually care about doing that, as it is to have a docs expert become familiar with the code. Some people can do both, sure. Some can’t.

If doc experts really are worth their weight in gold, I wish I saw more job openings to come in, understand a code base, write Stripe-level documentation, and create a good doc culture. I’d do that job all day and never grow tired. I think good docs require a set of uncommon, non-programming skills—and I’m not sure the majority of teams are willing to sacrifice velocity to write good code, achieve total test coverage, and produce top-quality documentation.