Documentation as Empathy

Docs are a letter to the next person — often yourself, six months from now.

[ trace // field response ]

Docs are a letter to the next person, and the next person is almost always you. Six months from now, the context you currently hold in working memory will be gone. What survives is whatever you wrote down, in whatever tone you chose to write it in.

Empathetic documentation answers three questions in order: what is this, why does it exist, how do I use it without breaking something. Most docs collapse the middle question, which is the one that actually matters. Without the why, the how is just superstition.

Write the docs you wish the previous maintainer had left you. Then go a little further — leave a paragraph about what you considered and rejected. The dead-end paths are part of the map.