Ordinateur
That Fun Font You're Using is Distracting
April 11, 2025There’s a few things that grind my gears while reading. Reviewing a document should feel seamless, but sometimes it’s like being a passenger in a car. With a bad driver. Racing through speed bumps. Braking at the last second… and all of a sudden you have motion sickness. Good technical writing makes complex ideas simple to understand. Ideas become cloudy when writers stray from conventional styles and formats. For example, if every document at your company is written with a specific font, your innocuous decision to use a new font for your document may make it surprisingly difficult to read.
No More Abbrevations
Nothing halts my train of thought faster than a confusing abbreviation. Each new acronym is a toll that forces readers to stop and reason about what it might be referring to. I was once on a team that had a “Domain Service” and a “Datastore Management Service”, which led to a smattering of “DS” and “DMS” across design documents. I question if the only reason the term Management was added to the name was so that people could distinguish the acronyms. After that, I worked on a service with a “Device Management” component and a “Dataset Management” component. Once again, things got confusing. Similarly frustrating are abbreviations in code. Even if it is idiomatic, I’ll never be comfortable with Kotlin’s insistence on the parameter name it for lambda expressions.
Why Say Big Word When Small Word Do Trick?
You must eradicate from your essence childish folly. In Season 2 of Severance (minor spoilers), one of the characters is told that they use too many big words. Eventually, he shortens this phrase into Grow up, and finally, Grow. A single word takes it too far, but the concise language is more direct and easier to understand (this is not an endorsement for abbreviations and acronyms). Sometimes we need to be verbose if there’s a precise concept we’re trying to explain, but I frequently see people use long words just for the sake of it. The biggest culprit is the word “utilize”. Unless you’re specifically talking about CPU utilization or something of that nature, I don’t ever see a need to prefer “utilize” over “use”. I’ve been guilty of dipping into the thesaurus too frequently myself, but I blame those bad habits on trying to reach page number quotas in high school English class.
Don’t Be Sloppy
Sloppy writing is an easy way to lose credibility. Typos, inconsistent headings, and mixes of bullet points/dashes are major distractions. They also make it seem like you do not care about what you’re writing. If you are frantically editing a document minutes before a review, the reader will notice the trailing sentence you left in paragraph three and sit there wondering what you were thinking.
This is Part 3 of a series where I document mental models about communication.