Home

Effective Technical Communication

2025-04-27 - Cameron Harder-Hutton


tl;dr: Text is a 1-lane road; sometimes you need a motorway, a train line, or a portal gun.

You and your long-time teammate swap half-sentences and get it. That's because you have this shared language and context that's been developed over many years.

Fresh eyes? They fill the blanks with assumptions and their interpretation of what you said can be totally lost. That's not cool for either of you.

Beyond Plain Text

Words run in one direction and assume everyone pictures the same thing.

Spoiler: they don’t.

Everyone ingests information differently. Speaking is probably the worst way to communicate a technical idea, shortly followed by text.

Other mediums:

  • Diagrams: shape the landscape, literally.
  • Videos: draw your diagram in real time and explain it.
  • Interactive demos: hand them the steering wheel.

AI tools make creating these things so easy now that I hope sharing ideas becomes a more and more low-context activity.

Map Message → Modality

There's also something to be said for using 'the best' medium for a particular message.

For example:

  • A single quirk is best explained with a few lines of code.
  • A whole system is best explained with a box and arrow diagram.
  • An API change is best explained with a PUML.
  • How to use an API is best explained with a working code example.

Don’t bolt a novel to a pull request and hope.

Respect Different Learners

  • Visual brains love colour-coded boxes.
  • Auditory folks lock onto narration + cursor highlights.
  • Kinesthetic types only get it playing around with the code.

Hit at least two styles and you'll be able to reach more people. Which will make you and your team more effective.

Practical Tips

For text, use headings every screenful and bullets always beat blobs of text.

For diagrams, use colours and shapes with meaning, and use the same nouns as your code.

For videos, script first and keep it under 3 minutes.

Close the Loop

Ship the communication stuff where the questions happen. Link on PR comments, bookmark in a Slack channel, etc. When confusion repeats, fix the asset, not the people.

Communication is just bandwidth, latency, and packet loss in wetware. Choose the right protocol and your idea ships intact.

P.S. the irony isn't lost on me that I'm communicating this thought with only text.


Have any thoughts? Send me an email!