Communicating techie stuff? Start with the 'why'

A student dropped me a line with this question:

Hi Clare

I enrolled in your class of clear and effective writing, and I loved it. Thank you for that.

If I could wish for something is on how to write effectively, if you're in a very technical field.

I work in IT, in development, and most documentation is boring, nonsense, mambo-jambo, or a combination.

I'd like some strategies on how this can be improved.

All the best.


It’s a really great question, Rui - and one I’m asked a lot. One strategy you can use is not to focus on the what of the thing you’re trying to communicate. Instead, focus on the why.

On this #WaistcoatWednesday, let me illustrate with an example of something a little bit technical that’s often badly explained: the offside rule.

Here’s a typical explanation of the fundamentals of the rule. It's from Soccer for Dummies:

A player is caught offside if he’s nearer to the opponent’s goal than both the ball and the second-last opponent (including the goalkeeper) when his team-mate plays the ball to him. In other words, a player can’t receive the ball from a team-mate unless there are at least two players either level with him or between him and the goal or unless his team-mate plays the ball backwards to him.

I suppose this explanation is pretty clear if you’re emotionally invested enough in it to concentrate hard. But it’s dull. And it makes my brain frazzle - even as someone who understands the rule.

And hit me with this kind verbiage when I’m standing in front of the big screen in my local pub? Sorry, but you stand no chance of convincing me the ref was right to disqualify that goal my team’s just scored.

What to do?

Well first, let’s step back a bit - and set the technicalities of the rule aside for a bit. Instead, let's think about the why of the offside rule - why it exists. Here’s how I’d explain the rule to someone standing in front of the big screen of my local pub.

Pretty exciting game, eh? Well, did you know the offside rule is there to keep the game thrilling?

The rule stops players hanging around the goal waiting for their team-mates to pass them the ball. If they did that, the game’d be boring. The players would just stand there waiting for their team-mates to kick the ball to them so they can knock it in the onion bag.

If they were allowed to do that, there’d be much less drama. Much less to-ing and fro-ing between the defenders of one team and the attacking players of the other. Basically, you’d end up with eleven-a-side golf.

So here’s how the offisde rule stops the game being boring. It says to prevent goal loitering, you need to have two of the other side’s defenders - including (usually) the goalie - between you and the goal. If you don’t have at least two of the other side between you and the goal, you’re offside.

Now, you can hang around the goal in an offside position all you like. But you won’t be penalised for it until the ball lands at your feet. When that happens, the other side gets a free kick. And if you happen to score, the goal won’t count. Make sense?

Now, I know this explanation is longer than the Soccer for Dummies explanation. But that's because it spends time securing the emotional investment required from the reader if they're to expend cognitive energy on understanding the rule.

So, back to  Rui - and your question about making your technical writing more engaging. How can you apply this to your own writing?

Well, let’s say you’re about to release an upgrade to a piece of software - and you want your colleagues to be as excited about the new release as you are.

You can’t just leap in with all the tech specs of what the upgrade does. First, you need to get your colleagues to care.

So warm your reader up. Get them excited and enthused about why they should install the upgrade.

For example, how will it make life easier for them? Will it save time? Money? Frustration?

Whatever it is, start with the why - and only then hit them with the technical what.