The Value of Good Writing

A lot of software engineers are very clever folk. Indeed, that almost goes with the territory - you need to be at least quite bright to do the job. However, a very large proportion of software engineers have extremely technical, even mathematical, minds. This is also important - we're operating in a field where exactness matters a great deal, and where we're thinking around problems that are, generally, deterministic in nature. That's all good.

However, what this also tends to mean is that many, if not most, software engineers aren't very good at technical writing - that's a different skill-set that requires different aptitudes. Indeed, many software engineers are remarkably bad at explaining what they're doing - very often they start from a position about two steps in advance of their audience, and then expect that audience to keep up.

This is why so many instruction manuals suck.

A big part of the reason that I'm posting about this right now is that I'm in a transition from one project, with a technology that I've been working with for almost 20 years, onto another project, with a technology that I've used extensively but never worked with. This has meant a very steep learning curve, aided and abetted by the documentation that has been available to help. It's fair to say that it has been... difficult.

I'm really not sure what the answer to any of this is. As noted, good engineering and good technical writing are different skill-sets, which means that people who can do both well are vanishingly rare. Obviously, a possible solution is to employ a separate team for the technical writing, but that only goes so far - sometimes there's no substitute for having built the thing when it comes to understanding how it works.

Mostly, though, this post is an aknowledgement of just how important good writing is (where 'good' writing is, of course, defined by the context - what is good in technical writing isn't the same as in a novel, for instance). And where you do find someone who is good at it, and especially if you happen upon someone who can do both things well (the engineering and the writing), make sure to value them accordingly!