Simplicity, Clarity, Humility
There is an old joke: “sorry this letter is so long, I didn’t have time to write a shorter one”.
It’s funny, but it’s true. Most tech writing (and other writing) these days is lengthy and hard to get through. AI is making this worse! There’s a reason everyone jokes about using AI to reduce emails to bullet points.
Most people have trouble writing clearly and simply. They just dive in and write usually. Most of what is produced is either stream of consciousness (which can be hard to read) or flowery and stilted language that people think is “how you’re supposed to write”.
The point of writing is to communicate an idea. The package for an idea is called a story, or, sometimes, a narrative. The first step to writing better is to think carefully at the start about the story you’re trying to tell. If you can’t get at least an idea of it into a sentence or two, you probably aren’t clear enough on what you want to say. Even very complex ideas can be started with a simple overall framing that helps the reader.
And then be careful about staying to that story! Don’t add anything that you don’t need. I don’t edit these a whole lot but most of the editing I do is removing things that I feel I’ve already said. Less is more if you want clear writing. If you find that you can’t express your idea clearly, you probably need to think a bit more about it before you write.
Finally, as with many things, a dose of humility helps. It’s easy to write something hard and leave it to the user to work it out. That’s a selfish and somewhat arrogant thing to do - it assumes you’re important enough to cause the reader some effort. I think great writing comes to the reader where they are - this is more work, but it’s a better state of mind. Help the reader understand your thoughts! Don’t make them work for it if you don’t have to.
It’s not easy to write well, particularly about complex technical topics, but it’s not mysterious either. Stop and think about your story, write clearly and simply, and center the reader, not yourself, in the effort.
(For those of you in Seattle, I’ll be doing a book reading at Brick and Mortar books, Wed Dec 11, 5pm)