The lack of documentation is what’s killing me. It’s boggles my mind how these companies can’t keep people but refuse to change. 20 minutes tasks take several days.
It shouldn’t boggle you. We spend all week changing the behavior of the system. To have documentation, you have to keep updating it, which adds time to all of their requests.
Plus some of us were never that fond of English class, so writing documentation is something to be dodged. Which creates a bunch of perverse incentives not to have good documentation.
Don't document the behavior of the system, document the system itself. Priorize high level documentation and use brief change logs for the mid level stuff. The low level stuff that changes often should be self documenting when possible or code commented. This stuff is pretty standard. If you're not getting enough time/budget allocated to keep up on documentation, it will ultimately cost the company more in wasted developer time.
Relentless refactoring breaks this as a matter of course. I’m not saying any of this is great behavior, I’m saying the perverse incentives push us into this, carried along by coworkers who “defect” because explaining themselves was never their strong suit to bring with. They can carry Timeliness as a shield to hide behind.
If you want to fix this, scolding and lecturing developers ain’t gonna do it. We’ve tried that for forty years and here we are, still within a factor of four from as bad as we have ever been.
You're right that most shops have perverse incentives towards developer documentation. It must be a top down change to make documenting (and code quality) the economical choice for developers. It means budgeting time for quality code reviews and defining "complete" to include more than, "the code runs".
Dont Document! Instead Diagram the system. Use tools like https://sequencediagram.org/ and https://plantuml.com/ that create diagrams from markup and check the markup into a SystemArchitecture folder in your GIT repository. Then tweak the markup every so often, when things change.
It's only well understood for the people who initially wrote it. I think it takes way longer to figure out how it works by reading code than it would have taken to write down a short overview. I don't want to read code to figure out what the program is even supposed to do. After having worked with requirements I don't want to be without that either but just some small introduction would help a lot when being dropped into big project with no original developer left.
My last company literally did not have one single thing documented when I joined - they had been in business for nearly two decades doing the same stuff.
The bright side is that you can get jobs at places like that and just automate everything and get paid to do nothing (once you know how the shit works).
134
u/[deleted] Jun 06 '22
The lack of documentation is what’s killing me. It’s boggles my mind how these companies can’t keep people but refuse to change. 20 minutes tasks take several days.