Why programmers don’t write documentation

Writing documentation is painful, because it reveals inconsistencies and fuzzy areas in your design. If you're not paying attention, you may associate that pain with the act of writing documentation. In reality, the problem lies with your designs.

I guess indeed many find it bloody boring. A chore to be dodged if possible. And also when doing some documentation work, because people are so deeply into the subject matter, they feel many things are obvious and need no further elaboration.

Documentation seems to follow two principles. It’s either (1) never complete, or (2) always outdated. As a general rule, you can always rely on it to never have the information you need, or to always have incorrect information.

Joking aside, documentation is great but it needs to be treated as importantly as the code itself. Treating documentation as a feature, rather than an afterthought or side effect, will allow it to get the funding and attention that it deserves.

There are a remarkable number of commenters saying no, documentation isn't hard actually. One question for those commenters:

How do you test your documentation? Properly test it, ensuring that it answers many kinds of questions for those who are new to the topic, and who haven't already been working on this project for months?

If you're not testing it, then how can you consider it done? Would you do the same with your software?

The vast majority of documentation that I see these days is bad in multiple ways. Most common is lack of coverage for important topics or cases, and I'm not even talking about things like "why this product is built this way".

I'm talking about stuff like:

- An API providing all kinds of methods for manipulating "Fribblers", and when you look at the Fribbler class it just says "This is the primary class representing Fribblers." No idea what this means or how it fits into the wider API? Good luck!

- Parameters or properties appearing in lists without any explanation of what they mean

- ... and that's assuming those parameters are even listed at all, which (often) they're not

- ... especially when those parameters appear in other parts of the documentation. "This method will work asynchronously unless you've passed the "borgle" attribute to the Fribbler constructor." There's a borgle attribute?!

- And this is all just for basic usage of a product. Want to contribute, or run tests, or anything else? Nothing.

Documentation needs usability tests, same as anything else which is primarily designed to be used by humans who may not have seen it before. But it's hard enough getting proper UX testing for the product, let alone its documentation.

Something the author didn't dive into - which is very important - is the audience of said documentation. In my 20+ years documentation is pretty much essential, but there is definitely a skill in documenting for a particular audience:

* Internal, non-technical users; what does the code do, why was it written, who currently owns it, when should it be run, how to run it, and what to do in case of failure. The more accessible, brief, and direct the better.

* Technical users; this is your README that usually doesn't need to be updated all that often. What is this code for? A quickstart for install/loading, dependencies, and the bare-bones set of functions, arguments, etc.

* Fellow implementers; the above README, but likely with a few additional notes of how the code is (high-level) broken up, and where to go for the most common things. This is where documented code is really good as well. I usually find the best code comments have always been A) NB: here's a drawn-out explanation of why the code does this, it's for a reason, do not question the code first unless you understand this and/or the above reason has changed, and B) in the future, you may want to do X, in which case you'll need to do J, K, and L and update M. Comments like those have saved me (from myself, even) so much grief and time.

* 3rd party users; this is where real documentation gets to be a monumental PITA and any company worth its salt will hire a technical writer or two. This is a very different skill than what's required for any of the above.

The biggest concern I see brought up again and again with documentation is that it becomes out of date quickly as soon as it's finished being written. This needn't be true. Internal documentation is just enough info for whoever is using it to know what it is, how/when to use it, what to do if it fails, and who to go to for more information or help.

Honestly though, the biggest problem with documentation has always been where it lives and how it's edited. Is it all repo READMEs and markdown? Are they google docs? A wiki/confluence? This is always where the breakdown happens. Programmers are comfortable with just being pointed to a repo and text files, while non-programmers want WYSIWYG docs somewhere central, which is the last place most programmers even think about. Wikis/confluence attempts to be a compromise that (IMO) no one likes. This - like task tracking - is a unicorn of software development.