How to Describe Your Technical Issue

Before others can help you with your technical issue, they first need to understand it. Thus, you will need to describe it to them. To do so, you have two options:

• either you get someone's attention first, and then do an improvised speech about your issue, or
• you document the issues in writing on your own, and you provide it for reference when you ask for help

Documenting the issue before you ask for help will make everything so much more efficient. You can send them the description, they’ll read it, and then they can either respond before meeting or at least know what’s up before getting to it with you. Handling technical issues this way shows respect for the time of the person who you are asking for help. It makes it more probable that you will receive the help you are looking for.

It helps you understand the issue

You’ve likely seen it in many places: explaining your issue helps you understand it well. Unfortunately, I see too many beginner programmers not following this advice.

When you explain your issue, you have to think about it more broadly:

• the context in which it happens
• what brought you here
• what have you tried so far

Those are things that you probably already forgot in the second or third hour of going in circles and not knowing why things are not working as expected.

Creating a simple code example of your issue forces you to play with the code. Making sure there is as little code surface involved as necessary to reproduce the issue is a great step in troubleshooting. It allows you to exclude all the possible sources of the problem—if your issue happens with only 10 lines of code you copied from the project, you can be sure the problem is there and not in the rest of your app.

It’s inevitable if you are going to work in this industry

There will always be some issue to document in your career. If anything, you can expect them to become more complicated or abstract as you progress.

You will need it to ask for help

The advantage of working in a team is that you can always get some help from your colleagues. As a beginner, you work on simple tasks, and thus you’ll often hit issues related to basics. As you improve, you will take on bigger tasks, and your challenges will be related to project-specific implementation ideas. With those issues, it’s possible that:

• there is no documentation, besides what the code author remembers—so you will have to discuss with them
• it will be more efficient to ask someone who already knows the code than it would be to have you learn everything from scratch

In both cases, knowing how to describe your issue efficiently will help you a lot.

You will have to make requests to other projects

It’s unlikely you will work alone on the whole project. If you are on the frontend, often the backend is a black box for you. What do you do when you need some changes in the black box? You describe your issue, and you request changes from your colleagues. It’s a case very similar to the previous one—this time, we need others to solve the issue for us.

You will need to explain your trade-offs

As you progress in your career, you will face more and more trade-offs. These are issues where there are no good or bad answers, but instead everything is in a gray area. Things like:

• deciding between a few alternative approaches to an implementation
• continuing development with the old legacy framework vs. modernizing the application stack—inevitably making it more complicated
• spending time on improving user experience in an unlikely edge case scenario

When you work in a team, it will be very helpful to document both sides of the trade-off, pointing out the issues you see in each of them. It’s a great way of explaining your thinking and having something to review with your colleagues before you follow any of the implementation paths. Besides, it would be a perfect documentation for the future reference.

You will have to report bugs

No software is perfect, and with time, you will start finding bugs in external libraries too. Depending on your situation, you can be forced to implement some ways of working around the issue in your code. The best long-term solution is to register a bug report in the third-party library and hope it will be fixed at some point. In the case of open-source libraries, it’s a way of giving back to the community as well.

The quality of your bug report makes a world of difference. A well-written thing makes it easier for the library maintainer—often an unpaid volunteer—to quickly understand the problem and find a solution that will fix it for all the users. A badly written one contributes to the noise in the project, and it is less likely to receive needed attention and a fix.

The form to fill out

To help you describe the issue, I’ll show you a form you can fill out and provide most of the necessary details. You can think about it as something similar to formal/informal letter formulas you’ve been learning in school: it’s a rigid form that should help you start. After getting enough experience, you will develop your own style while still covering what is important.

What you are trying to achieve

Main question—what is your goal? It’s serves two purposes:

1. Gives context to your question, and explains why it’s important. As you work on a task, it’s easy to forget that others will not necessarily know how your struggle fits into the bigger picture—even if they work at the same company or team.
2. Provides an opportunity to find easier or better approaches to your goal. Maybe you struggle because you overcomplicated the issue, or your implementation is something that will not be approved in code review—it’s good to use the opportunity to get early feedback on your idea.

What do you do & what do you expect

You already set up the broader context, so now let’s get into details. Provide code snippets or exact descriptions of what you are trying to do. Moreover, link relevant documentation to the API or methods you are using—in this way, your description will be easy to check for someone who is not familiar with all the tools you are using.

Explain what you expect as a result from the operations you are doing. If everything goes well, then someone taking a fresh look at your approach will already notice the source of the issue—a conflict between what is in the linked documentation and your expectations.

What do you get

Now, explain what’s happening instead. The answer to the previous question could ring a bell if your understanding of tools you are using is wrong, and the answer to the one here would make it obvious if the thing you are using is not working as expected. Again, the more detail the better—you can provide outputs, logs, and screenshots of failures. Include all context that could be remotely relevant to the issue.

How this could be explained

At the end, just share your guesses on what could be causing the issue. Be creative—treat it as a brainstorm session: write down all the ideas, and leave it for later to evaluate whether they make sense or not. This should help you troubleshoot the issue on your own—maybe some guesses will be easy to check quickly before going further. Sharing those guesses will make it easier for others to help you—they will see what you already tried, and they’ll let them know that you did your ‘homework’ before asking for help.

Example

How could a description like this look?

I’m calculating the total surface of multiple squares from the array of their side lengths.

My calculation looks like:

const sizeList = [1, 2, 4];

const totalSize = sizeList.reduce((value) => {
  value *= value;
}, 0);

I expect totalSize to equal 21 after the calculation, but I get undefined instead.

I have no clue what happens here. I check the reduce documentation, and I literally do the same thing. It’s either my browser that is outdated—but according to caniuse it’s not. Alternatively, my code is cursed.

Or

I’m working on a user setting screen.

I’m trying to save changes by doing POST request to /user/settings with:

{“data”:{“roundPrices”: false}}

Based on the documentation, I expect everything to work fine: API returning 200, and changes being properly saved in the database. Instead, I receive error 500 and an empty response.

It looks like:

• backend is simply broken
• backend API was changed, but the documentation wasn’t updated
• I did something wrong—in that case, some feedback form the API would be welcome

How you can use this description

So, you wrote everything down, but the issue didn’t get anywhere closer to being fixed? You can use the description in many ways.

You have a documentation to pick it up the next day

If you got to this point, it means you spent a lot of time on the issue today—and putting more time into it now will more likely contribute to your frustration, and not finding the solution. Luckily, you already have your write-up: it will bring you up to speed and give you an easier start the next day when you get back to the issue. If you use some bug tracking software, then you can store your text there; if not, then make sure you save it somewhere you will be able to find it easily when needed.

You have question ready to ask your colleague or a mentor

Hopefully, you have access to a developer who is available to help you. It can be a friendly colleague or a mentor. In those cases, it’s not necessarily their job to help you out; but they can be willing to give you a hand, especially if you make sure to make it easy and fast on their end. The time they spend on your issue is a gift for you, and it’s respectful to make sure everything goes as smoothly as possible.

Technical issues are usually complicated enough to require so many details that writing is the best suited tool for providing it all. If you try to explain it verbally—some stuff will be left out. Sharing the screen and showing code in action provides all necessary information, but it’s more time-consuming, requires bringing together both people at the same time, and it’s better suited for more complicated cases. It makes sense when pair troubleshooting is required to address the issue, but it should be used after simpler approaches have failed.

You have details for a new ticket

If neither future you nor your mentor manages to solve the issue, maybe you found a bug in another piece of software. Again, your work of documenting the issue comes in handy—you can use it as a part of the description of the ticket you will be registering for another team in your company or the third-party provider of the libraries or tools you are using. The more complete the description, the easier it will be for others to provide you with a solution. Plus, people appreciate well-written tickets, so you may be able to build some trust and goodwill with people on the other side.

A practice in synthesizing ideas

You experience your bug in the context of your application—with all the complexity of the whole codebase. The easiest way to communicate the issue to outsiders is to pinpoint what exactly is not working as expected and isolate it from the application. This is a good exercise in synthesizing the ideas to their core: you strip everything that is superfluous and leave only the most important part. This skill is something every programmer uses all the time—for example, for naming things or organizing the code into classes or files.

Write. It. Down.

I’ll repeat to avoid misunderstanding—I’m talking about writing exercise here; that is, when you are done, there is some text output available. It’s not thinking about the issue, or day-dreaming about what you could write.

As an example, for a text like this, it takes me about 2~3 hours from knowing what I want to say to having a text I can share. What takes so much time? The actual work of clarifying and refining the ideas. There is no way of getting around it; the only options are:

• doing the work and getting the results
• leaving it incomplete

Share it in the comments!

Want to give this process a try? You are welcome to post a write-up of your current technical struggle in the comments! Maybe some other reader will be able to answer your question.