Documentation can't save us from being human. No data translated from one medium (brain) to another (paper) and back (brain) is 100% efficient. But documentat

Documentation can't save us from being human. No data translated from one medium (brain) to another (paper) and back (brain) is 100% efficient. But documentation is not only 'tutorials' / how to do something. Documentation is also 'design' / what to do, 'requirements' / why we're doing it, 'changelog' / why we are making the tweaks we are making in the process. I'm enough of an antiquarian to be interested in why the phone guy who installed the phone lines for the theme parks did what he did...turns out burying the phone lines directly in the dirt was for a particular reason (cheap / good enough) and for decades, it was indeed good enough. But because nobody read the roll up paper showing the phone line runs, the lines were destroyed when someone came along and installed a roller coaster with a greater than 180 degree turn in that spot, cutting the bundle. The documentation wasn't missing data, but the humans failed to read it. We do forget things all the time, sure. But don't blame documentation when humans don't read it. The weakness in the system are humans, always. Now is not the time to give up documenting things. All salutes to the ongoing flamewars over 'code should be self-documenting means I never have to write AnYtHiNg down' aside, someone said civilization advances by the number of things we can write down...because we only have so much wetware / RAM / brain space. Someone said this and I'm stealing from them: under similar conditions, the wimpiest charcoal on the flimsiest napkin lasts longer than the sharpest mind. In this knowledge-based industries, no matter our particular focus, we individually would be served better by improving our communication skills, namely documentation of more than just the brittle business processes and API interfaces, but the who/what/when/where/why of what we're doing.