Something changed quietly
in how decisions get made.
The thinking moved.
It used to happen in places
other people could see.
A thread.
A pull request.
A meeting where three people
argued about two approaches
and one of them lost
for a reason everyone heard.
Now a lot of it happens
in a window that belongs to one person.
You described the problem.
You got two options.
You pushed back on one.
You found the constraint
that made the other obvious.
That was real work,
and it was good work,
and then you pasted the result.
The code landed.
The reasoning did not.
Six weeks later
somebody asks why it works this way.
The answer existed.
It was in a conversation
that nobody else can open,
that you do not remember having,
that has scrolled past the point
where you would ever find it again.
This is not an argument
against using the machine.
It is an argument about
where the output goes.
The conversation is a workshop.
Workshops are private, and messy,
and that is fine.
But the decision is a shared thing,
and shared things
live in shared places.
So when you come out of one of those sessions
with something you believe,
pay the two minutes.
Write the alternative you rejected.
Write why.
Write the constraint
that made the choice obvious,
because the constraint
is the part that will be forgotten first
and needed most.
Put it where the code is,
or where the code's history is,
not in a document
nobody will open again.
None of this is bookkeeping.
It is the difference between
a team that knows why it is here
and a team that inherited a shape
and is afraid to touch it.
The test is simple.
If you were gone,
and the next person had only
the repository,
would they understand
why this shape
and not the other one?
If the honest answer is no,
then the decision is not
actually made yet.
It is just implemented.
– Serguey Asael Shinder
Top comments (0)