You wrote the setup guide.
It is short,
and it is clear,
and it works,
because you followed it last month
and everything came up.
Then somebody new follows it,
and on step two
they are stuck for most of a morning.
The guide says
run the service locally.
It does not say
you need the VPN on first,
and the certificate installed,
and a setting in a file
you created two years ago
and have not thought about since.
You did not leave those out
to save space.
You left them out
because you cannot see them anymore.
That is what knowing something
does to you.
Every step you have taken
a few hundred times
stops being a step.
It turns into
part of the floor.
You do not decide to skip it.
It simply does not arrive
in your mind as something
somebody might not know.
The same happens
when you explain a design
and leave out the one constraint
that makes it make sense,
or answer a question
with a word only your team uses,
or review a beginner's code
and cannot understand
why they did not just do the obvious thing.
It was obvious to you.
It was obvious
because you learned it
so long ago
you forgot that you learned it.
The worst part is
the better you get,
the more of the floor there is,
and the less of it you can see.
Your expertise
is the thing hiding the gaps.
So stop relying on
reading your own explanation
and deciding it is clear.
It will always seem clear to you.
Watch somebody else use it.
Give a new person the guide
and sit beside them
and say nothing.
Not a hint,
not a nudge.
Write down every place
they pause,
every question,
every time they open another window
to look something up.
Each pause
is a step you stopped seeing.
Put it back in.
Do it for the guide,
for the design document,
for the talk you are about to give.
You will be surprised
how much you knew
that you did not know you knew.
– Serguey Asael Shinder
Top comments (0)