Documentation for the Next Person: The Small Changes That Matter

This began as a thirty-day experiment in writing documentation for the next person. I wanted evidence from ordinary days, not just the kind of week when motivation and time happen to cooperate.

The experiment centered on recording decisions, tradeoffs, examples, and the safest first change. It felt almost too small at first, which turned out to be a sign that I might keep doing it after the excitement passed.

There are limits to this approach. Different seasons create different constraints, and a practice that reduces friction today can become an obligation later. I now review the arrangement when the work starts serving the system instead of the other way around.

Eventually, new contributors could act without reconstructing months of context. The change was visible to other people before I trusted it myself, because the work required fewer apologies and last-minute rescues.

If you want to try this, begin with the smallest version that produces real information. Keep it long enough to observe an ordinary week, note where it breaks, and change one variable at a time. The point is not to copy my routine; it is to notice what your own circumstances are asking for.

— Ada Mensima