on documentation

The best documentation answers the question you have right now, not the question the author thought you’d have.

Most documentation is written from the author’s perspective: here’s how the thing works, here’s the API, here’s the full reference. Useful eventually, useless when you’re stuck.

The documentation I actually want: what problem does this solve, what’s the minimal example that works, what goes wrong and why.

Write docs the way you’d explain something to a colleague who’s smart but has never seen this before.