Effective issue reporting for non-technical people

When someone emails me or comes to me to say “The site is not working” or “The App stopped working” with no other information there is a part of me that gets a little disappointed. Not in the work that potentially needs to be done to fix the problem (when the problem is not a user error) but in the way that the issue was communicated. Those two statements as the start of a conversation is fine, but on their own they exemplify a lack of understanding for how to effectively communicate a need.

In software development there is a great structure for how bugs and tasks are logged that I find useful even when not dealing with software behaviors:

Issue: App crashing on iPhone when saving user profile

Expected Behavior: User should be able to update profile information successfully

Observed Behavior: After changing any user information and trying to save any information the app crashes

Environments Effected: iPhone 7, 7 Plus running iOS 10.3.1

ReproductionSteps: Open app, try updating name in app, observe crash

Screenshots: If possible, images or video documenting the problem and how to reproduce it

Relevant Information: issue not present in previous release prior to API updates. May be related

This looks good in text, but I also loosely follow this format when I communicate with others to keep my objectives clear. The format and order is not rigid as long as most of the first three major points are covered: issue, expected behavior, and observed behavior. These three seem the most applicable to any situation where a person has to communicate a need or give feedback. Translating this is also good practice since I am frequently asked to discuss technical issues with people who don’t have domain knowledge or self-identify as nontechnical. This makes sure I do not give opaque or confusing statements that don’t communicate what I want.

Here are a few nonoptimal and optimal statements as examples:

This process document is wrong.

I am trying to understand the process document and see confusion in how the objective of each step is measured.

You left something out, this doesn’t work.

Reviewing your last code delivery I saw a missing part that keeps it from running correctly.

You can do better than that.

You put in time on this but the outcome doesn’t reflect your efforts and experience.

This report is confusing.

That report you shared doesn’t have your usual attention to detail, please a take a look and make the marked corrections.

Another thing to note is that all of these rephrased statements are actionable. After reading or hearing these a person can either perform a task to address the concern or ask a targeted question to get much more granular detail. If the response to a statement is for clarification or context then it has not succeeded to communicate, and should be examined to understand what was missing. There is a danger in assuming that others know everything we know, but there is nothing lost in concisely sharing information so a person can begin address a situation.

Is this to say that shorter phrases are bad?

Not at all if it is within the context of a conversation. When it’s a stand-alone statement that doesn’t communicate the scope of what needs to be done then it is not effective. It does not communicate the situation and, in my opinion, can create a lack of sophistication for how communication is handled within the team. A significant factor in measuring if a corporation will succeed depends intrinsically on how well information flows across the roles within its teams. Information silos, frequent misunderstandings, non-uniform vocabulary, and unclear directives will drain productivity and erode confidence; this should be avoided at all levels of the organization from the C-level all the way across to the interns.

Won’t this disrupt the team and slow things down?

Not a all, quite the opposite. If you consider the back and forth that happens with clarification and finding examples, or even having to re-engage with outside parties. Taking the initiative to confidently represent an issue to the team in an effective and potentially actionable way increases productivity by decreasing the time it takes to get started on addressing the need. The more relevant information that can be brought to the team when making a request the stronger the potential for success for the team.

And finally…

Making it a priority to check if a statement has sufficient detail, describes the issue, and provides a way forward to address the need should be all of our goals to make communication more efficient and clear.