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,

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.