This is a rant. It’s not a well-reasoned argument with tons of supporting links because I’m just going to start writing until I’m done ranting.
The idea that programmers can’t write docs is a huge load of crap. It’s a very common view shared by technical writers, and it’s time that we killed this idea. Because it’s not true. Because we’re putting down our coworkers as a way to justify our own value. Because it’s a dangerous generalization that pits Us vs. Them, that draws artificial distinctions between “what we do” and “what they do.” It keeps us isolated by emphasizing false differences, and it kills the very idea of collaboration when collaboration is becoming more important than ever.
This article is an example, and it’s just one example of a damned common idea. I’m not blaming this one writer for this idea, and I honestly don’t mean to throw the author under the bus. This nasty idea has infected a huge swath of our profession; I’d need a whole fleet of busses.
The author uses some common, negative generalizations to argue that developers can’t write docs. The main argument: “developers just can’t have the viewpoint that’s needed for good documentation”
Why can’t they have that? Because they’re too close to the product. Even though the author notes that the same “closeness” is what allowed the developers to create a usable product, they simply cannot be trusted to write the documentation.
That’s nonsense. We’ve seen these arguments before. Technical writers clutch them like some nasty, tattered security blanket. I’m sure I’ve made the same argument. I was wrong.
Because by that logic, tech writers should never touch API docs because they just can’t have the viewpoint to write good code examples!
The explanation is that the poor, too-close developers will merely document the product’s features. But a noble technical writer can save the day by creating task-based documentation!
Here’s the thing: maybe no one taught the developers about product docs, about what works and what does, about what their users are looking for.
Because when I started as a tech writer I did not know those things. I wrote boring, feature-based documentation. I managed to learn, so I’m pretty damn sure that your average developer can also learn how to do that.
We didn’t graduate with a degree in empathy. Or maybe that’s just me.
Maybe writing is a skill? Like programming? And, hey, did you know that sometimes developers can learn different programming languages? It’s true!
But why can’t those poor, silly developers just write good docs?
“Technical documentation requires a certain user-centric focus that is just not possible when you’ve been up to your neck in code for…weeks, months, or years.”
First: writing code doesn’t turn you into an unfeeling robot. You don’t lose empathy, or forget what it’s like to be a human who needs help to learn an unfamiliar product. Developers do, in fact, interact with other humans! I’ve seen it! I’ve even…gasp…TALKED to a few of them! Over lunch! (It’s true! They eat real, human food and everything!)
Developers aren’t sealed away in sterilized containment pods at the end of the day to protect their precious brains from any improper, non-coding thoughts.
Usability best practices? These. Are. Skills. They can be taught.
Developers can learn, but, like everyone else, they need a reason to. Maybe that’s personal interest, or maybe it needs to be valued by engineering leads and executives and seen as something worth developing.
Hell, maybe we can help!
Second: this also gets into the “SME” worship thing. We need to stop treating developers as the vessels of holy knowledge, who must be approached with awe and wonder and only spoken to with our heads bowed in fear and respect.
They’re your coworkers. They know things, you know things, and it’s perfectly fine to ask questions and share information and talk about your weekend plans and make dumb jokes and whatever else goes on during an average day at work. A “subject matter expert” is just someone who can answer your questions. Just call them “my coworker.”
Developers aren’t gods. They can and do write great, clever code to do great, clever things. And they screw up. They get tired and write shitty code. They then write shitty patches for shitty code. Sometimes they have enough experience to understand that good docs makes them better programmers. Sometimes they don’t have time because “document your code” isn’t at the top of their task list. Sometimes they’re insecure and worry that if they document their code then they won’t be needed. But mainly: They. Aren’t. Gods.
I work on the product team. You know what the engineering team does without direction? They work on random stuff they think is cool. And sometimes that stuff has little business value. It’s like they’re human or something.
Is this a problem with tech writers who are part of engineering teams? Are we just too close to have a rational view? Are you sitting with the developers but still insistent on being separate from them? Is this more “impostor syndrome” nonsense where we feel we’re somehow lesser beings because we don’t write working code, so we reassure ourselves that we are the only ones who possess the divine talent to write wonderful, usable, (and eloquent and beautiful) documentation?
Because if you’re buying into the “developers are the most worthy” nonsense (but can’t be trusted to write documentation), then it’s time to sit down with customer support, product management, marketing, sales, etc. and get a different view of the world.
And hey, have you ever found something interesting, then poked at it until you figured it out, and then moved on to something else? Congratulations! That’s classic developer behavior.
Tech writers don’t own the world’s supply of curiosity and ability to learn new skills. Stop building a wall between you and your coworkers and start teaching and collaborating. Stop basing your value as a technical writer on the outdated idea that “only coders code, only writers write.” Are you worried about losing your job if you teach a developer to be a better writer?
Would you lose your job if a developer helped you become a better coder?