Communicating with Dev

Writing a Response to Dev

We should be using the following 4 guidelines to help us put together a helpful and clear picture for dev of the issue.

• How are we expecting it to work?

• How is it currently working?

• When did it stop working as expected?

• What have we tried to fix it?

How are We Expecting It To Work?

Dev is not always familiar with the day-to-day of how the products they make work. They don’t use ICC often like we do, and aren’t often involved in the regular work we do. This means they don’t have the background we may think is obvious for how certain features or functions may work.

Therefore, it’s important to include in our response how we expect the feature to work normally. An example of where it is working as expected helps too.

This feature isn’t showing up and I can’t figure out why.

This feature should be showing a box on this page (URL), but it’s currently showing nothing. On this other site (URL), it’s working correctly.

“The feature isn’t showing up” is not specific or helpful enough. Dev needs to know what the feature should be doing and how it should be showing to be able to compare and see what might be causing the issue.

How Is It Currently Working?

This ties into the previous question, but we also need to explain how the problem is manifesting to the best of our ability. This way, dev team can compare how it should be working with how it is currently working. The more detail we can provide, the better, and an example of where it IS working as expected helps them a lot.

The box was showing up before, but now it’s not working.

The box was showing up before at this URL with some code – see my screenshot of a site where this feature is working correctly – but now it seems to be missing from the code entirely, and I can’t find any reason for it to have been removed.

The “now it’s not working” is also not specific enough. We need to explain how it’s not working exactly – is it not showing up? Is it showing, but malfunctioning in some way? Dev needs specifics as to the behavior of the problem.

When Did It Stop Working As Expected?

Dev puts out almost weekly updates to our platform and other features. Sometimes, these updates have unexpected consequences that we couldn’t predict would happen. For this reason, we need to include (to the best of our ability) when we realized this stopped working. The client may be unable to provide this information in a support ticket scenario, but we can try to provide as much info as possible, such as the last time we noticed it was working, or any other hints we may have received in the process of investigating the issue.

This box stopped working and now it won’t show.

I noticed that on Friday, this box was working, but when I returned to work on it on Monday, it had stopped showing up correctly.

The first response is not specific enough. Even if we don’t know the exact day or time it stopped working, we can let them know when we last saw it functioning correctly, and when we first noticed it had stopped working.

What Have We Tried To Fix It?

Finally, we need to be as clear as possible about what we have already tried to fix it. Dev is going to want to know if we’ve already tried some basic troubleshooting measures (and will likely push it back to us to do so, if we haven’t yet), and it will help them to know anything else we’ve noticed or attempted in the process. This may not always be applicable (there are certain items we know to send to dev right away), but in any scenario where we are struggling to find a solution ourselves and need to pass it on, we need to be clear about documenting what we have done to investigate and troubleshoot.

I tried a couple standard things to fix it, but it’s still not showing up.

I tried turning the feature off and back on again, as well as checking the CSS to ensure there was no styling preventing it from showing. I also tried removing all of their third party scripts to see if any of them were blocking the feature from running and that didn’t solve the issue. I’ve also attached a screenshot of the console error I noticed when looking at the page in question.

Dev does not know what “a couple of standard things” are, so it’s best to just lay it out specifically. The more we can tell them we already tried, the quicker they can get to resolving the issue instead of needing to make sure we did our due diligence before sending it their way.

Troubleshooting Expectations

On the subject of what we’ve tried to fix it, the expectation is that we have tried to the best of our ability to do everything we can to fix it on our end before sending to dev. This includes, when applicable:

• Check for console errors and see if we can resolve them

• Check to see if third party scripts we can access are causing issues by removing them one at a time

• Remove and re-enable the feature if applicable and accessible

• Check templates, CSS, page and site toggles etc to ensure that nothing on our end is causing the issue

General Communication Guidelines

Be clear and concise in your language, and use screenshots or URL examples when the location or behavior of a bug is hard to explain. Try to make sure you’re using standardized language (ex. Image Rotator – the actual name of the snippet – instead of image slider or banner slider) to avoid confusion.

Assume that the person who is going to read the ticket knows nothing about the feature/bug you’re asking them to fix. While dev is generally familiar with the names of some of the features, they often don’t know how they work on a day-to-day basis. For the most clarity, it’s best to assume that whoever reading it is not familiar and explain clearly. This ties in to the “how are you expecting it to work” section – we should be explaining what we expect to see without assuming the other person knows what we would expect to see.

Make sure to include as many details as you can about the problem and any troubleshooting you’ve done. The more detail you can provide, the better. It is important for dev to know about all the actions you’ve taken and what you’ve already checked so they can formulate a plan to tackle the issue. It also helps them resolve faster because they don’t have to check with us to make sure we’ve tried everything we can first.

It’s okay if your language is technical or specialized – you aren’t trying to explain to a dealer or an AM. Although we need to be as clear as possible, we don’t necessarily need to explain in non-technical terms. We just need to make sure we are using the right technical terms! Make sure we’re referring to features by their name in ICC, and copy-pasting code or styling as needed to make our point.