NeverSawUs

I've heard it said that coding, as a skill, rewards those who have a high tolerance for remembering lots of trivia.

Trivia, here, means "knowledge divorced from context". That is, the sort of thing you'd hear in a bar trivia game, such as "what year was Waterloo?" or "what are the names of the active volcanoes around Portland?" The observation is funny in a useful way: it subverts the image of programmers as magicians by reframing it as a sort of stubborn tolerance for an unfortunate situation. However, the important thing isn't really the volume of trivia one can memorize, but the desire to continually contextualize trivia both for oneself and for others.

Contextualizing knowledge is tricky. We don't help each other do it as much as we should.

A professional StarCraft player, Sean Plott said the following:

I think one of the biggest things that irks me is when someone who's trying to teach me conflates the learning process with knowledge. Which is, "Sean, in this situation, you need to build X because that counters their build."

That is someone sharing a tidbit of knowledge, not considering the sequence of steps of learning that are necessary to even use that knowledge, or what that knowledge is sitting on top of."

Much of the craft of software engineering (AKA programming alongside other programmers) is about communicating knowledge in context so that others may build a mental model of the program being developed. The best programmers I've worked with recognize that programming is theory building, and so give great weight to leaving artifacts behind that communicate meaningful context for their decisions. The aforelinked author, Naur, makes a useful recommendation about what to communicate:

That which helps the next programmer build an adequate theory of the program.

Even so, it's no small feat to identify all of the necessary context that future readers might require, let alone to marshal it into natural language in an easily understood fashion. As a profession, we're terrifically bad at sharing context. I care a lot about sharing adequate context! I know I'm still bad at it, though. What can we do?

Identify your audience. Are there gaps in your skills? A delta in your experience levels? What might they not know that you are taking for granted? Be gracious: you might misestimate them: apologize up front for retreading ground. This is incredibly important when talking to folks early in their careers.

A brief aside: back in 2007, my first paying programming gig was maintaining a college radio station website & DJ song log by myself. I was self-taught: a feral ¹ programmer. I knew how to program, sure, but I didn't know about things you'd absolutely take for granted, like version control. As part of a archival project, another programmer came in to help digitize the station's vast CD and record collection ². They had many suggestions that were, in retrospect, incredibly insightful. At the time, though, I didn't have the necessary context to make that knowledge actionable. I pushed back on a lot of it because I simply couldn't understand it. I was frustrated and in turn I was frustrating³.

I met up with that programmer a few years later, after I had some professional programming experience under my belt. To my great surprise, so much of what they said made sense to me. They had been clear this entire time: it wasn't them! It was me! Look out for these sorts of gaps. It's not always so pronounced: it might be that you're talking to someone whose expertise is simply in a different area.

To some degree part of the problem particular to programming is that the solo act involves considering many different courses of action and weighing their outcomes.

That is, you spend time thinking about the problem before typing your solution. One of the developmental stages commonly seen in programmers is to go from working the solution out in the editor to thinking the problem through before committing to typing it out. The more you practice simulating the effects of edits ahead of making them, the more automatic it becomes! The more automatic it becomes, the more efficient you become as a programmer. It's a virtuous cycle right up until another programmer joins you on the program.

In my experience, pair programming helps a ton here. Pairing forces both programmers to verbalize the unconscious act of simulation ⁴. This can feel like a terrible slog at first, but it's useful on a number of levels:

• By talking through one's thought process and deliberating on approaches in tandem, the mental model is shared, reducing the lottery factor of the program.
• It's a great way to share cognitive strategies & problem solving approaches which are otherwise hard-won.
• Verbalizing the process requires surfacing the unconscious process to conscious examination. Flaws in thinking can be identified and fixed.
• It builds rapport, which is key to maintaining a healthy social structure around the program. Since the program will inevitably reflect the structure that built it this is is essential work.

Just remember: you and your pair now share context that the rest of the organization may not have. Luckily, you've verbalized that context! It's still incumbent on you to record it for others. Even if you don't combat this by pairing, it's helpful to consider that the act of conveying context is in tension with the act of coding.

There are no silver bullets here: communication is difficult. Practice contextualizing what you've learned. Teach others. Find communication you admire and emulate it. But most of all, don't give up: continually seeking to improve your communication skills is an excellent way to distinguish yourself as a talented engineer. Giving up early -- or worse, imagining that you have no room to improve -- is a surefire way to frustrate your peers.