Over the course of the weekend we tried to install a new door bell for our house. The old system is really old, falls apart and works only some days. So we bought something from a respectable German engineering company named Gira. They make high quality products and we had prior experiences with their parts. We also happen to really like their clean design language. The reviews online spoke about easiness of installation, “connect just a few wires”, nothing can go wrong there.

So… how hard can it be?! (Queue picture of Jeremy Clarkson here, before he got old and rich 😉)

Turns out, we spent large parts of Saturday and the whole of Sunday, more than 8 hours, and achieved nothing. We got the help of my father-in-law as well. He lived in this house before we bought it from my parents-in-law, so he knows his way around the conduits and everything. But! somehow somewhere there are some electrical conduits lying underground here, no-one knows where they are, how they are connected and frankly, how some things are even working at all in the house/garden. Because everything is a mess. Image a junior developer trying to build a complex system that gets things patched onto from other juniors. Then along comes an intermediate trying to improve things, without fixing the underlying mess. Well perhaps you have an idea in your head how it might feel to operate in such an environment. It’s a horror show.

I haven’t felt so much frustration in a long time. One thought lingered in my head throughout the weekend: If only there was some documentation about this electrical chaos! Back, when this house was built and the wiring installed, and than patched onto, and things were modified, the people responsible…well they probably didn’t think much about documenting stuff. Because it was all in their heads, and fresh and “they knew what they did”. But nobody thought about 20 years down the road, when no-one remembered anything. We could have easily installed everything and worked around all the edge cases if only we had some written (or painted, or recorded — I’d take anything by now) documentation.

In my job I am lucky to build applications and software for my clients. The documentation usually revolves around elaborate ReadMes, Wiki texts and images. I’d like to admit, I never had a mentor or teacher who showed me how to properly document software. It was all learning by doing. If you don’t mind, I’ll take some future episodes of this newsletter to document (see what I did there? 👅) my findings and further thoughts about this topic.

What about you? Do you regularly document? Would you mind sharing your horror stories about incidents where docs where missing and you severely felt it?

Yours, Holger

PS: Did you do some weekend programming, some Katas or somethings different? I came across this resource after already writing to you: https://programmingpraxis.com/