Every reproducible homelab, every modular CV pipeline, every chess engine I’ve built has taught me the same thing from a different angle: the person most likely to read your documentation is you, six months from now, with no memory of why any of it works.
So I write for that person. Not the impressive comment that explains what the code obviously does, but the quiet one that explains why it’s shaped this way — the constraint, the dead end I already tried, the thing that will look wrong until you remember the reason.
Empathy at a distance
Good docs are empathy for a stranger who happens to share your name. Write them while the reasons are still in your head, because they leave faster than you think.