How to write better documentation by learning about the "Bloomfield Bridge Mystery"
Photo by Pixabay: https://www.pexels.com/photo/an-opened-old-book-161366/
"No one writes down the real reason for infrastructure projects."
Through Mastodon (definitely the better Twitter 😛) I was made aware of the text "The Mystery of the Bloomfield Bridge" by Tyler Vigen.
This text starts humble. It's just someone asking why this particular Bridge was built in Bloomfield, Minnesota (US). As it seemed superfluous and simply not needed.
Spoiler: It was built 70 years ago primarily for children visiting a nearby school (which now seems to be long gone) and the church (still present).
But just when it seems that Tyler Vigen had consulted all sources. Spoke to anyone he could imagine and still had open questions. And, more importantly, was in need of a primary source backing up his theories and link his findings. He received the following tip:
"No one writes down the real reason for infrastructure projects."
What the woman who gave him this tip meant was: Projects (especially civil ones) have a political side which is seldom actively documented. As it was the case with this particular bridge project.
Curiously I first understood it in the following way:
Rarely anyone notes down the volatile Zeitgeist knowledge. The: "We are currently at this point of our journey. We came here because of A, B and C. Now we have the following problem with C. Hence we try D."
But it's this knowledge which enables me to provide better solutions and guidelines to my clients. Contextual wisdom is important.
"Can't you just talk with your client?"
Sure thing. And I do. After all I'm not tight-lipped.
Another aspect which I encounter regularly: There is a plaque at the bridge. Prominently declaring: "Federal Aid Project FAI 494-4-32 Minnesota 1959."
Ok, yeah.. That seems to be the project which built this bridge.
Apart from that? Well, just another cryptic abbreviation which we can use for our research.
Yeah.. And this is usually the time when I tell the story of this big IT company and it's KF1 test environment.
This company switched all its technical systems, all its processes to the UTF-8 character encoding after having used Latin1, also known as ISO-8859-1, for decades. But as UTF-8 provides support for characters from any alphabet & language it seemed only logical to use this. After all it made expanding into markets with other alphabets (like Cyrillic or Greek) easier.
Each and every process was built up a second time in this KF1 environment. Too big was the fear that a single not-migrated process could wreck havoc. Each process was tested end-to-end and all systems were switched during 3 weeks. Which left the company somewhat inoperable for this period.
Sometime during this project I asked: "Hey, out of curiosity what does KF1 mean? What does it stand for? Everyone just uses the abbreviation."
Nobody, not one single person knew it. Some said they did know it. Once. Years ago. After all this project was running for several years. And in all these years no one saw it necessary to note down the full wording of this abbreviation. Not in one single wiki page or document.
And now we are back to our bridge in Bloomfield, the plaque and our quote on top of this article.
Another sad aspect is: Each and every person which Tyler Vigen could have interviewed is dead.
An aspect which I do encounter often in a similar form:
"Oh, we don't know precisely why it was done this way. All colleagues who built this system are in different parts of the company now or have left it."
What do we learn from this? Just because something is as clear to you as glass. And you think it's absolutely obvious, self-explaining and everyone knows it anyway. - Then this is still not a valid reason to not document it.
After all archaeologists and historians can tell you a thing or two about this.
You don't know what I mean with this? Well..
Until today we just don't know what the Xylospongium (a sponge on a stick) was used for in Roman lavatories. (Yes, Wikipedia writes it was used to clean the butt. But (pun intended) this theory is old and doesn't match Roman hygiene customs - as there were only few per lavatory. Current consensus seems to be that it was used like a toilet brush.
But we can't say for sure. We simply don't know as we have no reliable primary sources.
Oh.. No. Wait, we do have some. They complain that the Xylospongium is often used in a wrong way - but WITHOUT describing how this misuse looks like. (Sounds familiar to you? 😂)
And now don't get me started on the roman dodecahedron.