Good code documents itself.
But there’s a lot of context outside the code that informs it. There’s architecture and design decisions about which language to use, about whether it’s micro services, monoliths, containers, clouds, or mobile apps.
There’s legal frameworks and security certifications.
Code determines how. Tests determine the what. But documentation tells you why and when. Documentation supports future you or the next team member to understand what the reasoning behind that code was. It gives your present self grace for what you know now and don’t know yet.
Document the requirements in just enough detail, but document the decisions in depth. Working software, that’s suitably readable, is the best way to describe what it does. But understanding how that code came to be has a value you only understand after you forget how it came to be.
Document why you built this, but not that. What was the experiment? What was the context? Is it time to experiment again? Is it time to chalk the experiment up to experience and move on?
Be nice to yourself. Comprehensively document decisions.
