Note: On persuasive technical writing and clarity of thought

Sep 8, 2023

This note was originally a Thread.

Working remotely on a technically complex project at a large organization has forced me to spend a lot of time doing persuasive technical writing.

What I've learned is that this style of writing is an incredible tool for improving one’s own thinking. It forces you to clarify your logic and acknowledge gaps/flaws. I'm convinced that being forced to write like this has dramatically improved my understanding of the space relative to a world in which I simply had to represent my ideas verbally.

Being concise is what takes 95% of the effort for me, but also what provides 95% of the value. If I can’t write it concisely, often that means I don’t fully understand it yet, or it’s not an elegant idea (or both). But, forcing myself to find a way to make it concise often drives me to both an elegant solution AND a full understanding. Sadly it can take tons of effort.

But it’s a minor miracle to me that iterating in a doc, trying to make a post concise, can often get me to that place of understanding, when just staring into space a scratching my beard will not.

I’m reminded of the quote:

If I had more time, I would have written a shorter letter

Which has been attributed to many people in different variations.