My personal experience is that all forms of coding, and all forms of documentation share a common weakness: the humans who create them.
My first shell scripting effort happened because there wasn't anyone else to do the job, so I had to learn sh scripting on the fly. The result was a set of sh scripts that I wince to think of now. I rarely was aware of the best solution, and was working under time pressure. However, I documented exactly what was going on in every part of those scripts. Both the logic behind the flow of the process, and what I was intending for the various lines of code to do.
While I did write the scripts under time pressure, with a focus on getting things to work, I also took the time later to make the scripts do everything I knew how to do to proactively detect and handle just about any error condition I could think of and that I could find a way to handle.
The end result is that when I handed that particular build system off to those who came after me, they were able to understand what was going on and update them when needed.
Since I handed them off, that set of scripts has been in regular use for several years with only cosmetic enhancements.
What's the moral of this story? I poured months of my life into doing everything I knew how to do to build those scripts to be stable, flexible and friendly to learn. I've run into other script like the ones mentioned, which are a nightmare to work with. My opinion is that it all comes down to the element I find missing in so many things: quality.