We need to kill some dangerous myths (programmers can’t write; writers can’t code)

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?


12 thoughts on “We need to kill some dangerous myths (programmers can’t write; writers can’t code)

  1. I have always subscribed to the belief that developers and engineers might very well be excellent writers (I know an electrical engineer who was the best technical writer I’ve ever met.), but it is not what they do best. They went to work in their field because it is what they do best. What I do best is learn to understand what they have created well enough to allow other, non-technical, users the ability to use the product. Doing my job well frees up the developers and engineers to focus on what they do well, and everyone benefits. The only issue I have ever had is from the flip side. I don’t think they cannot do what I do, but they all too often do not believe that I can understand what they do because my degree was not in a STEM field. The antagonism works both ways. Use your human empathy and common sense to break down the barriers and you can make an effective team.

  2. I am the only technical writer in the company. I work in software R&D with about 50 developers and guess what, they write the documentation, not me. I help them when they need it, I manage the wikis on which we publish and, yes, I write code. So, I call bullshit on the idea that developers can’t write (OK, some are half literate, some point-blank refuse, but most manage).

    However, before you throw everything overboard and leave it to the developers, I do think you need to consider the fact that creating technical documentation is a lot more than “just” writing. Will it be in line with the house style, is it properly structured, is it of a tone and style in accordance with not just the audience and purpose but also the existing documentation? Is it maintainable? Can it be produced to a short deadline and is the developer able to work according to an established process, know how far they are and when they will complete?

    To take a bad analogy, anyone could probably install plumbing in a house. Would it work? Probably. Would it work well? Maybe. Would it use the best materials and techniques? Probably not. If it is running over budget or time, would they know where they can safely cut corners. Could they do it quickly, cheaply, and reproducibly? Almost certainly not. And, having got one house fixed, would they be happy about having to do another 200 houses?

    Yes, developers can write – and I can program in C, Fortran, C++, Pascal, Algol, Basic, RTL2, Perl, Python, PHP, XSL, Lisp, and quite a few other languages. My code isn’t pretty, but it usually works. I would feel sorry for someone having to maintain it, or even debug it but, I am a writer not a developer.

    It’s isn’t about ability. It’s about skills in an industrial process. Developers can contribute but they will always see it as a secondary activity and, once you get into the fine detail, I am pretty certain they will lose interest – which brings me to my final point. Most developers that I know (except for a very rare few) hate “doing documentation”. I love it, I’m passionate about it. That’s why I became a technical writer more than 30 years ago in the first place. If you love your work, it shows. If you don’t, it doesn’t matter how good you are.

    Would I lose my job if I became a better code? No. Am I worried about losing my job if taught a developer to write? Hell, no, that’s what I do most of the time. BUT, teaching a developer to write does NOT make them a technical writer. The would have to learn at least a dozen tools, technical illustration, graphic design, some user interface design, some cognitive sciences, XML, SGML, and a hundred other things.

  3. 100% agreement — developers CAN write and writers CAN code. The issue is all about division of labor. Why SHOULD developers write docs? Aren’t they better utilized if they can stay focused on code? It’s costly to switch gears from code to docs, and it doesn’t make sense to force developers to do that. But nowhere does that imply that developers can’t write. In fact, it puts even more onus on the writer… A good tech writer has to ADD VALUE.

    Can writers code? Sure… I do it all the time. I’ve implemented various content delivery mechanisms… Simply because the devs didn’t have the bandwidth to do it. And we needed these mechanisms.

    Not all writers can code, and not all devs can (or want to) write. But there’s nothing intrinsic to either job title that makes it necessarily so.

  4. It’s good to see folks telling stories that support Neal’s rant here, but I’m afraid that they also miss the point a bit. I’ve been writing software docs for 15 years now, with a background in European history, and I have never encountered a dismissive programmer if I go to them with intelligent and curious questions. Never. I’m sure that I’ve been lucky, but I’ll also give myself credit for bringing both respect and research to my conversations.

    I also don’t think that the point here is that tech writers don’t bring value to the table. Clearly we do, or our jobs would not still exist. But I could not agree more with Neal’s point, which is that there’s far too much of a tendency on the part of writers to treat programmers like some sort of alien species. When writers perpetuate this attitude, which I’ve found everywhere ever since I started in software, although never in the groups that I’ve worked with, they help build the barriers that get in the way of good customer experience (no matter what sort of customer you’re writing for).

  5. I sympathize with the rant. My experience at the 1:1 level is similar to Golden Unicorn’s description–you get the respect you earn. This was also true when I was a developer, so I don’t see this as being unique to being a technical writer.

    Unfortunately, where I think the notion and myth needs to be busted is more in the organizational realm and not the interpersonal one. In my experience, organizations create and then exaggerate the differences between writers and developers (and developers and testers, and developers and marketing, etc.) for any number of reasons: financial, cultural, etc.

    Some of the things I’ve seen that create and sustain the divide:

    — Using completely incompatible tools: writers use content management tools and developers use code management tools. Sometimes they start out the same (and we’re seeing this cycle start over with git repos and Markdown-oriented authoring systems), but they invariably diverge as each discipline tries to optimize to different goals. Eventually, it all becomes so cumbersome that it’s no longer practical and the cycle repeats.

    — Not coordinating release deliverables (code/docs/support/training) from the start — and then resourcing accordingly. I’ll just say “Fred Brooks” and leave it at that. When the pressure rises, each discipline hunkers down into its own specialization–often at the expense of the other. If only there were some way to collaborate and achieve a common goal…

    — Treating tech writers as 2nd class contributors. Devs get the latest and greatest hardware & software, Writers get hand-me-downs. Devs get early info on (and contribute towards) what’s coming up. Writers get 2nd-hand info (if any) as to what’s going to ship soon. Devs get training and development budgets. Writers get, well they’re lucky to have a job. Devs get bonuses and raises, Writers get…well, see the last point.

    The fundamental reason behind much of this seems to be that developers are seen as contributing to revenue, while writers are seen as contributing to cost.

    What contributes to that perception? I think in large part it is because most developer content (i.e. documentation) is “given away” free whereas software is written to produce revenue. But that’s the exact wrong way to look at it.

    It appears as though your rant is contagious 🙂

  6. Reading over my response (rant) above, it seems a bit one-sided. Such is the nature of a rant, I suppose, as the alternative would be a well-reasoned analysis. While I’ve seen all the the situations that feed, or are fed by, the myths in Neal’s post, I’ve also seen (and thoroughly enjoyed working in) more constructive environments. So, perhaps, the myths are starting to crumble.

    I know for a fact that:

    There are product teams that do consider the documentation as critical as the code to the product’s success.
    There are writers who get the same hardware and the same access to the product code as the developers.
    There are writers who are in the same pay scales as developers.
    And, there are teams who are all in it to win together, as a team.

    For writers, the tricks are to not contribute to reinforcing the myths and knowing how to bust the myths when you come across them.

    1. Thanks for the comment, Bob. Fortunately, my experience lately has been a lot closer to your update than your original post. I’m currently part of our product team (I’m also the entire documentation department), and I report to someone who understands the need for good documentation and supports my role. Of course, she also has very high standards for the docs, so it’s a lesson in being careful what you wish for! 😉

      Your last sentence is an excellent summary of my point: we need to stop contributing to these myths, and that means on both sides (our views of ourselves as tech writers, developers’ views of us). If my blog has a theme, it’s that tech writers can’t afford to be complacent, and can’t sit back and let other teams dictate the boundaries of our roles and usefulness.

      1. I’m glad to hear that you got your wish! My most recent product team was like that as well (and now I’m spoiled 🙂 ). We need to communicate far and wide that such teams exist and hold them up as the model. Or more practically, demonstrate the advantages of that model to make everyone else want to do it. The steno-pool model of technical writing has got to go, Unfortunately, that won’t happen until we (i.e. us tech writers) can replace that model with a new one.

        To do my part in this, I think I’m going to print (and attribute, of course): “tech writers can’t afford to be complacent, and can’t sit back and let other teams dictate the boundaries of our roles and usefulness” and stick it to the mirror in my bathroom so I’m reminded of that each day before I head out the door.

      2. That’s an excellent point about demonstrating the value: I think I’ve done a bit of that, but just in bits and pieces.

        Go ahead and use that quote: I find it very easy to fall back into the heads-down mode of tech writing; I need to remind myself to be aware of that, too!

  7. Hi. I am so happy I found this site. Recently, I left proposal writing (after 10 years) and found the technical writing field completely different.

    For someone who is used to writing online help and user’s guides, what can I do to become relevant in the field again?

    Which tools do I need to learn first? I am used to WebWorks and FrameMaker.

  8. One unintended consequence of the notion that “developers can’t write” is that it lets them off the hook for providing any documentation. I’ve been creating developer docs for over 30 years and have met developers who are great writers, but most are so busy they usually only provide the skeleton of the reference section. My value added includes many prescriptive examples, additional information about putting procedures in context, and filling in the blanks in the reference section (a common hole is missing information about exceptions/errors that can only be found by reading the code).

    I also haven’t seen anyone discuss the common situation where English in not the developer’s native language. It’s not unusual to find missing articles in docs written by non-native speakers. It doesn’t make them a bad writer. I recall once seeing a dev using wording from one of the methods I updated in a similar method. I made a point of complimenting her in the next team meeting.

Comments are closed.