Composing the Writeup

ADVANCED TOPICS
ANALYZE PCAP
OBTAIN PCAP
GET STARTED
Share Results
Communication is Key
3 min　|　 Ross Jacobs　|　 August 8, 2019

Table of Contents

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.

General Structure

___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:

  • Problem Statement: What’s wrong in a sentence or two?
  • Problem State: What work did you do / Are there any new developments related to the problem?
  • Analysis: What are the effects of this new problem state?
  • Action Items: What needs to be done and by who?

Possible Sections

This is one possible ordering. Your needs likely differ.

Problem Statement

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.

Problem State

When communicating work that you’ve done with others, share details that are key to the person understanding your message. For example:

  • Devices/interfaces you gathered data off of. Include topologies as appropriate.
  • If you are not pre-filtering the packet capture, include the relevant filters.

If your description of the problem is lacking, you may want to gather more data.

Analysis

Wireshark makes it easy to be an expert

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:

  • How does the packet capture demonstrate the problem?
  • What should be done based upon that conclusion?

Action Items

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.

Further Reading

While the following articles focus on asking questions, they are quite relevant in thinking about technical issues correctly.

Email Style