I can be a very verbose writer, long run on sentences meandering across lines, with no sign of when or where the thread of an idea will finally terminate its arduous journey to a conclusion. Did that make you tired? A few years into my career, my manager pointed this out to me.

I had reached a point where I was communicating daily with senior and executive management. I’ve also worked almost entirely in startups and smaller engineering departments. Everyone is busy all the time. Presenting information in the most digestible format is critical to get your point across. My manager, in a brutally honest piece of critique, told me he rarely reads beyond the first line of anything I wrote. His advice, focus on short declarative sentences.

Over the subsequent years I’ve moved between management and IC a few times and the advice has continued to put me in good stead. Having mentored, managed, and worked with a range of engineers, it’s advice that many could benefit from. So let’s dive into what constitutes a short declarative sentence, and what doesn’t.

Here are the key concepts:

• Make one point at a time.
• Use direct language.
• Avoid unnecessary setup, qualifiers, diversions, or fluff.

How I used to write

Let’s say you’ve been investigating a performance issue. You might be writing a short summary of your progress so far to share with your team or manager. Maybe it goes something like:

I’ve been investigating the performance issue with the /widget endpoint and so far it looks like a database issue but our observability only captures high level metrics, we should look at getting more fine grained metrics, so I don’t have visibility on whether there’s a specific query that’s just slow or whether it’s something like lock contention.

While all the information you’re trying to communicate may be in there, there’s no prioritization. If I read between the lines, I might surmise that you want to surface more fine grained metrics but there isn’t a clear and specific ask. The final segment is pure speculation. It adds no value other than to try and seem knowledgeable, without actually having any facts.

How I’d write it today

/widget performance investigation

• The database is showing increased query times in our APM.
• Our observability only captures high level metrics.
• Is there somewhere I can see detailed per-query metrics or should I look at how we can surface these?

Let’s break this down:

• The bolded title immediately communicates what the message is about. If this were an email, this would be your subject line. Easy for recipients to scan and decide “do I need to go deeper.”
• The first bullet communicates what the investigation has turned up so far.
• The second bullet communicates a blocker you’ve encountered in progressing further.
• The final bullet contains a specific call to action. It’s explicitly requesting a response that will unblock the investigation.

People may have follow-up questions and that’s fine. You don’t have to include every piece of information upfront. In fact, you want to communicate the minimum amount necessary, in the fewest words that still form complete sentences.

The constructive feedback I received so many years ago has helped me communicate more effectively. As my own career progresses, I continue to understand from that manager’s point of view too. Short declarative sentences get read. They get responses. They get shit done.