Sunday, 23 October 2016

The 5 Reasons Developers Don't Like Writing Documentation

A popular gripe amongst technical writers is that a lot of developers don't like writing documentation.  In fact, a small cottage industry of tool makers has sprung up specifically to help companies get developers to provide some form of documentation by making the process as easy and coding-like as possible.  If you've used tools like OpenAPI (formally Swagger), JavaDocs or Jekyll then you'll be familiar with this kind of tool.  The aim of this cottage industry is to make writing documentation as much like writing code as possible, which means allowing users to focus as much as possible on the syntax and not the semantics.

These tools are all very useful, but whilst they may be efficient ways of creating certain types of documentation, they treat the symptom and not the cause.  A lot of (most?) developers don't like writing documentation.  Why not?

Having worked with my fair share of developers over the years, I've seen and heard many answers to that question, but they all reduce down to one of the 5 following reasons:

  1. It's boring
  2. It's difficult
  3. It's messy
  4. It's dangerous
  5. It's unmanly
Let's unpack these a bit.  I'm going to refer to "developers" below, and by that I mean "the developers who would say that this is one of the reasons they don't like writing documentation".

1. It's boring

Of all the reasons, this is the most obvious and overarching.  Developers find writing documentation to be a boring task.  Perhaps a more accurate word would be uninteresting, because writing documentation is not an interesting task.  If you don't find explaining and teaching interesting, if you have no interest in understanding the mental perspective of a target audience, if you think formatting and writing styles are dull or unimportant, then writing documentation is not going to grab your attention.

2. It's difficult

This is equally as obvious, but a lot less admitted because people don't like to admit they can't do something.  This is especially true for that sub-set of developers who think that documentation is unmanly (see below) or who generally pity and/or mock non-developers as being somehow less intelligent than developers.  If you've worked in software for any length of time you'll know exactly the type of developer I mean.  The fact remains that many developers simply lack the writing skills to write documentation well, or if they have the basic skills they don't have the confidence to use them for fear of looking stupid.  In fairness that's not an attitude specific to developers; lots of people don't try to do things because they're scared of looking stupid, but if you've ever mocked someone, even gently, for being "just" a technical writer, you're probably not looking forward to a chance to demonstrate that you can't even remotely do their job.  Better to sneer than look dumb.

3. It's messy

A big part of the reason that documentation is difficult is that natural language is organic and messy and often follows illogical rules.  Developers have spent their careers, and often many years before, learning how to use languages that are clean, designed and above all logical.  Developers only have to worry about syntax, but semantics?  No.  No, no no.  Semantics can often seem to preclude right and wrong, so for a developer who's used to the binary test of "compile/doesn't compile" or "passes unit test/doesn't pass unit test", writing in natural language for others to critique without having any real sense of what's correct and what's incorrect is a deeply terrifying thought.  The fact that only the very best and brightest end up working on natural language processing at the companies that are any good at it just solidifies the notion that writing in natural language is a one-way ticket to looking stupid unless you're brilliant at it.

4. It's dangerous

Not in the sense of physical danger (especially since everything's electronic now and you no longer have to worry about paper cuts or dropping a heavy manual on your foot - shout out to my old-school veterans!), but more in the sense that once you've written documentation people will a) associate you with that documentation and possibly product, and b) people might actually want you to write more documentation, possibly even on other bits of code.  Worse case scenario: People see you as someone who can write documentation so you'll have to do a lot more of it.  There are plenty of developers who would genuinely consider jumping out of the window rather than be the developer that people go to for documentation.  Writing documentation can lead to writing more documentation, and very soon that can lead to having a reputation for writing documentation.  This is not good, so it's best to be very bad at it or very awkward to get any documentation from.

5. It's unmanly

Correctly or incorrectly there is an attitude amongst some developers that writing documentation is not a manly occupation.  For those people that aren't developers this might seem at first sight to be a completely bizarre attitude, but whilst I think it's wrong, it's also not an attitude that comes out of nowhere.  For a start, men are vastly overrepresented in development (I don't need to link to the stats on this; Google will find you a large number very quickly) and women are vastly overrepresented in technical writing (refer to this article as an example of the trends in writing).  Whether this is cause or effect can be debated ad nauseam, but the point is that developers are much more likely to have worked with female technical writers and male developers.  The second reason is that technical writing requires a person to collaborate, think about the needs of others, step into the user's shoes and above all display empathy.  This sounds similar to what are known as the "caring professions" such as nursing, and as such stereotypically seen as being more appealing to women then men.  It's the equivalent for some people of doctors and nurses; why be a nurse who has to change bandages, empty colostomy bags and give bed baths when you could be a doctor who gets to analyse, diagnose and fix people, maybe even save a life.  And notice that a nurse "has to" whereas a doctor "gets to".  There is an alpha-male competitiveness to many developers, and that doesn't fit well with putting the needs of other people first. 

Entirely anecdotally, I've found that the female developers I've worked with over the years generally have no problem writing documentation, and the ones that do only have a problem because other (male) developers sometimes see writing documentation almost as a sign of weakness.  In some development teams writing the documentation can have almost as much of a gender bias as the old school "women make the tea" attitude, so female developers in that scenario would rather not write documentation as it will pander to the idea that they're not "technical" enough like a "real" developer.  Conversely, if I think of the 20 most vociferously anti-documentation developers I've met, they've all been alpha-male types.  Correlation is not causation, and all that, but I do find it a very interesting concurrency.


Every reason I've ever seen or heard for developers not writing documentation can be reduced to one of these 5 reasons.  I don't want to tar all developers with the same brush; many developers write documentation happily, and many of those do a great job.  Equally, I don't want to accuse all developers who don't like writing documentation as thinking that it's unmanly; I suspect this is a minority view that will only become rarer in the years to come.  If you think I've missed a principle reason or you've got an opinion on which reason is the biggest prevent of developers writing documentation, add something to the comment below.