Why don't developers write documentation?

Posted on 06/29/2021 by Ken Gregg

Professional software developers do write documentation. It’s one of their responsibilities. I have personally written huge amounts of documentation over the years.

Sometimes a developer will participate in writing specifications before the software is written. Sometimes they write documentation in tandem with developing the software. Sometimes they write documentation after the software is developed. Sometimes they write documentation for someone else’s code, that another developer neglected to document. Sometimes they write documentation for third-party code acquired from outside the organization.

Now, if you’re really asking why some software developers don’t like to write documentation, that’s a different story. For those with a passion for programming, the act of writing code and debugging is interactive, engaging, and provides immediate feedback. Writing technical prose, on the other hand, is a one-sided form of communication, with feedback that arrives relatively infrequently. Many developers would just rather write and debug code than write documentation. And many software developers might not yet have developed the written communications skills required to write effective documentation.

Nevertheless, developers are expected to write documentation of various types. All jobs have some responsibilities that are less fun to do than others.

In some organizations, a software developer might be required to work with a technical writer, to document APIs, user interfaces, communication protocols, etc. While the actual writing might be done by the writer, the software developer still needs both the verbal and written communication skills to accurately describe how things work. So, there’s no getting around the need for communication skills.

Personally, I like to put myself in the shoes of the next person who has to maintain my code, the developer who will use my new set of APIs, the end user who will have to figure out how to install and use the new application I’ve written, etc. I find it challenging (in ways different from programming) to anticipate what will be important to them, what questions will enter their minds, what terminology they might not be familiar with, etc. Would I rather by writing code? Probably. But writing documentation is part of the whole package — it’s part of the job.

developer communication written communication skills program documentation software development software engineering programming best practice best practices documentation software documentation documenting software