Take any system you work on and ask why it is shaped the way it is. Not what it does. Why.
The code will tell you what. The tests will tell you what, in more detail. What none of it tells you is that the odd second write exists because a customer was promised something in 2019 that nobody has ever been allowed to withdraw. Or that the retry limit is three because at five the vendor started billing per attempt. Or that the team tried the obvious clean approach already, abandoned it six weeks in, and everyone who knows why has since left.
That kind of knowledge has never been written down much, and it has always been valuable. It is about to become more so.
The machinery around us is getting extremely good at reading what is there. Point it at a repository and it will describe the system, find the inconsistency, propose the tidy refactor. What it cannot read is the conversation that never reached the code, the constraint that was never a ticket, the option ruled out in a corridor in March. Deciding what should exist keeps needing somebody who was in the room, or who took the trouble to find out what happened in it.
So take the trouble.
When you hit something that looks wrong, find whoever has been there longest and ask what they remember, before you conclude that the last person was careless. The answer is far more often a constraint than a mistake.
When you make a decision, write two short paragraphs about the options you rejected and why. Not documentation. A dated note, sitting next to the thing it explains. In five years that note will be the most valuable file in the directory.
And when someone leaves, spend an hour with them on the things only they know. Nobody ever schedules that hour, and everybody regrets it about four months later.
The tools will keep getting better at answering what. Being the person who can answer why, and who leaves a trail so the next person can answer it without you, is quietly becoming one of the most durable things you have to offer.
– Asael Shinder
Top comments (0)