mbehan

You'd Be Surprised What People Don't Know

Have you ever thought about trying to explain something, but it's so obvious that you assume everyone already knows?

Have you ever thought that maybe there are lots of things you've never even though about explaining, because, well they're even more obvious than that?

I've been thinking about this lately and I know for sure I can answer yes to the first question, and almost certainly even more so to the second. I've avoided unnecessary explanations - success! Except I've come to realise that a great many of the explanations I avoided, code comments I didn't leave, blog posts I didn't write, were missed opportunities.

As Daniel Jalkut put it in a recent episode of Core Intuition, sometimes we know Rome too well. In his metaphor a lifelong resident of a city is less suited to writing a guide for visitors than a more recent arrival whose freshly acquired knowledge is less ingrained. He was talking about marketing his product, but it immediately resonated with me for a slightly different reason: bringing new developers on to an old codebase. The one or two people who've been working on the app for the last 5 years won't know what a new developer is going to struggle with, they may not spot that the fact that you have to do x,y and z before you call some particular function is non obvious.

With recent events there has been lots of sharing and explaining about a couple of things that I thought were pretty obvious. Hand washing, and exponential growth. It turns out a lot of people don't know that soap is the thing that cleans your hands and that you don't have to double things very many times before the numbers get huge. I'm really glad that people have been sharing because it wasn't until I really thought about it that it made sense that not everyone knows this already and that I just happened to know them too well. It turns out my obsession with computers and taking chemistry in secondary school with a teacher that now that I think about it was way too excited about soap than is normal made me uncommonly equipped for current events.

I've learned that it's important to examine how we've come to know something, and to consider if it's reasonable to assume others will have had similar opportunity to come by this knowledge when deciding if something is worth explaining, commenting on or sharing. I've resolved to document earlier, comment better, and in general share more. I'm also planning to make newcomers central to my efforts to fill in documentation deficits and improve developer onboarding on older apps.

Hopefully you didn't already know all this.