"we are lazy assholes who can't keep docs up to date, therefore docs are useless"
Is essentially the argument i see over and over again. And every time i start a new project and that project has docs or uml or whatever I appreciate it. Even if it is a bit out of date, it's way better than nothing.
In my opinion, every project should have a readme file with instructions for running the project locally, and ideally also a high level visual representation of the system.
It should be separated into sub systems/modules for separate functionality and each module could have it's own set of readme and high level visuals. In addition, modules should have small coupling points, typically interfaces and these should have documentation comments describing what they do, inputs, outputs etc. APIs should have something like a swagger doc.
> "we are lazy assholes who can't keep docs up to date, therefore docs are useless"
Rather: managers do not highly value work on documentation, so many programmers care little about it. If writing good documentation was valued more by managers than implementing feature stories, the situation would be different. Incentives do matter.
We are the engineers. It is up to us to tell non technical managers what's important. They don't know shit, they're just there to handle the shit we don't want to handle, like talking to clients or upper management or whatever.
It's all just bad excuses for not doing work properly. Writing clean and well documented code very quickly becomes faster than writing a tangled undocumented mess.
> It's not a question of laziness, it's just that people don't do it so you need automated tools to do it for them
Sounds a lot like laziness to me. It may be more accurate to say it's because people don't care. I've seen projects full of typos. Ive seen projects where basically everything had been duplicated not once but twice because they wanted a slightly different version of the same website so instead of adding some configuration or otherwise finding a reasonable solution for it they just went and copied hundreds of files and prefixed their names before making a couple minor changes and leaving the mess for someone else to discover. No mention anywhere of the fact that this had been done, nor why.
These are the actions of people who don't give a shit. Whatever problems they create are someone else's problems. The way i see it, if you care about your work you'll make sure the code is readable, well documented and so on. If you don't, you won't.
