Quicklinks: Expert Information
When writing your message, you want to come off as polished and professional as you can. This page covers how to communicate the technical parts.
When in doubt, use fewer words.
It is possible to have a page-long paragraph of an email. Nobody will read this.
It’s better to break it up into small sections that each have a purpose. Make it easy for the recipient to skim and find the information relevant to them. Generally speaking, you’ll want to have at least four sections that answer these questions:
This is one possible ordering. Your needs likely differ.
It may be tempting to add more than one issue to an email. This is a mistake. You will get a response that reciprocates your lack of clarity.
Introduce the problem in one sentence. By making it immediately clear what your email is about, you make it easier for your recipient to care. If your problem statement has more than two sentences, follow it with a section called “Background” or “Description” and move the extra content there.
When communicating work that you’ve done with others, share details that are key to the person understanding your message. For example:
If your description of the problem is lacking, you may want to gather more data.
Wireshark makes it easy to be an expert.
As the “domain expert” here, you need to explain what the data means. And if you aren’t, triple-check that the way you talk about protocols and the problem state is accurate. Data is important when discussing a problem, but needs context to give it value for the reader.
For capture-based evidence:
Specify which people need to do what based on your analysis. It is easy for there to be a general abdication of responsibility when the who and what are not clear. Your reader should never ask “What is this email asking me to do?”
Something like this would suffice:
@Alice: Test the lotus-o-deltoid model turboencabulator that is surmounted atop prefabulated amulite.
@Bob: Make a presentation to our investors on Feb 31, at 9:99.
While the following articles focus on asking questions, they are quite relevant in thinking about technical issues correctly.
Email Style * 2019-06-26, Lazarus Lazaridis, Composing better emails