Why programmers don’t write documentation

I just make sure I supply a detailed what, why and how comment with each commit and then copy and then just export that for documentation. Also spending time putting thought into a standard system for properly naming variables in your app goes a long way. A lot of people like to abbreviate things just to avoid typing. Modern IDEs allow autocomplete so there is little excuse for this. The only time that is acceptable is in a very small very self evident class, method or function that does something very simple and atomic. I try to avoid this as well since I like to be able to do named search and replaces later if needed. Too simple of a variable name will lead to collisions with sed/awk ect

>fuck off with your clever code

Stupidly Simple Code is the best code, but it is also possibly the hardest to write from a programmer perspective.

I don't understand 1) Why every company doesn't use Github/Gitlab to do documentation. and 2) Why Github/Gitlab don't offer a cheaper account type for employees that don't code or even write documentation to make internal docs available to everyone.

It's easier to maintain documentation when it's closer to the project. You can also automate a lot of its parts for your projects. You can create template projects and use tools like cookiecutter every time you create a new repo to have the basic structure in place. That's already half of the road.

I suspect that one big, big reason developers don't document is this: most developers work on making relatively small changes something that came before them and is poorly documented. There is no documentation for them to maintain in parallel with maintaining the code.

There are barriers, both psychological and real, against documenting changes that ride on an undocumented ball of mud.

The psychological barriers amount to, "what is the point". Why document some insignificant part of something that is documented, on the whole? For instance, imagine a windowing system that is mostly undocumented, except for the wonderful 15 page treatise on its scrollbars, because a compulsive documenter touched the scroll-bar code. Which was 13 years ago.

The real barriers stem from the problem that the documentation depends on other documentation, much like code depends on other code. If you document a small part of some undocumented whole, that documentation has nothing to refer to. There are no certainties it can rely on, provided by other documentation, no context. This attaches a barrier to the documentation: the first person to document anything at all in that system has to provide the context for that documentation, and start the process.

That barrier brings with it psychological barriers: the fear of the effort (how much time it will take to start the documentation effort) and the perception of futility: that nobody else will come on board, and so that will be the first and last piece of documentation ever written, effectively making it a waste of effort.

For these reasons, even programmers who write excellent, lengthy documentation for their side projects can become reluctant to document something on the job.

Developers working on an undocumented ball of mud might put their documenting effort into detailed summaries of their changes and the reasoning behind them, rather than into building a coherent description of the system: in other words, to write that documentation that is more likely to save them from any predicament caused by their changes, rather than to help someone else navigate the system as such.

my docs are a single page full of one liners for practical issues that have organically arisen several times over the years, with a table of contents at the front.

As I said, I write good docs, but no-one will read them until they have been caught out 3 times asking obvious questions had they gone to the doc first. If I am not around, I know the docs will be abandoned immediately despite it representing a tome of hard won knowledge that saves an incredible amount of aggregate time from never needing to figure out how to do the same task twice.