Communication

Clear communication is a core engineering skill. People read your code, messages, docs, and updates far more often than they run your code. This is how the team thinks together. Write so that a tired, busy colleague can understand you quickly.

Almost every costly mistake has a communication failure behind it. Maybe an assumption was never stated. Maybe a status looked fine until it suddenly wasn't. Maybe a decision was explained to one person but not the rest. Good communication means putting the right information in the right place, at the right time, in a form the reader can use.

The goal is shared understanding, not just sending words. So lead with your main point. Write things down where people can find them later. Match the message to the reader. A regulator, a product manager, and an on-call engineer each need a different version of the same facts.

Be clear and considerate

• DoLead with the main point: the conclusion, the request, or the risk. Put the supporting detail after, for those who need it.
• DoWrite for your audience. Match the depth and the words to your reader, whether that is engineers, leadership, or non-technical people.
• DoUse channels that last and can be searched (docs, tickets, PR descriptions) for anything that matters beyond the moment. Avoid channels that disappear.
• DoState your assumptions and what you are unsure about. Say what you do not know, not just what you do.
• ConsiderWriting the short version. Respect the reader's time by cutting words, not adding them.
• Do notHide a critical detail — a security risk, a breaking change, a blocker — in the middle of a long message where it will be missed.

Keep people informed

• DoShare status before you are asked. Report progress, delays, and risks early, especially when something is going wrong.
• DoClose the loop. Acknowledge requests, confirm decisions, and follow up so people are not left wondering.
• DoAsk questions early and without shame. An hour of someone's time is cheaper than a week spent on the wrong path.
• ConsiderWriting down decisions made in calls or in person, so the agreement is recorded and shared, not just remembered.
• Do notGo quiet under pressure. The moment you most want to disappear is the moment the team most needs an update.
• Do notAssume that silence means people agree, or that something obvious to you is obvious to everyone.

Self-review checklist

• AskIs my main point in the first line, or is it buried?
• AskWill this reader, with their context, understand this and be able to act on it?
• AskIs this written somewhere it can be found again, or will it be lost in a chat history?
• AskHave I said what I am unsure about, not just what I am confident about?