#documentation

Daniela Baron writes up some great advice and a thorough list for thinking about documentation on a project.   It’s one of those where you find yourself aggressively nodding along, but there’s one that really stuck out because it feels so often overlooked. So often, people focus on well-written code not needing extensive documentation, and that can be partial true in terms of understanding what the code is doing.

Good names and understandable code can’t, however, explain the why of how a certain section of code is written. We talk about making sure code can be intention-revealing, but it’s never going to be able to communicate the state and context of the project at that specific point in time and how that informed the approach.