#documentation

Even being aware of this and actively trying to avoid it, I’m sure I still make this mistake all of the time.  

If someone’s been driven to Google something you’ve written, they’re stuck. Being stuck is, to one degree or another, upsetting and annoying. So try not to make them feel worse by telling them how straightforward they should be finding it. It gets in the way of them learning what you want them to learn.

Pretty sure it can’t be said enough. Hopefully this is a reminder that sticks and helps me remember to trim all that garbage out of my writing.

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.