As you may be aware, I very much like building things. Almost by definition, this means that I’m very often in situations where I’m out of my depth, as I always try to do new things that I don’t quite know how to do yet. Luckily, I have a whole bunch of knowledgeable friends whom I can ask for help.
However, I noticed a pervasive problem when asking for someone’s help: It takes way too long to describe the issue I’m having. To make matters worse, conversations are usually synchronous (either chat or phone calls), which means that I’m wasting a bunch of the limited time they’re gracious enough to give me on trying to get my thoughts in order and describe the problem well.
This is very suboptimal, and I’d like to propose a better way here.
Describing the problem
When asking someone for help, I’ll first ask if they have some time to help me. If they do, I will tell them I will formulate my problem and send it to them in written form. This respects their limited time, as they can get to my issue at their leisure, instead of forcing them to dedicate all their attention to me, as they would have to do with a phone call.
In the process of trying to clarify my thoughts, I will very often realize what I have to do to solve it, and solve the issue myself. Even if I don’t, though, I’ll have a better grasp of the problem and it’ll be much easier to explain to someone unfamiliar with it.
In general, I tend to follow a simple process, whose goal is to preemptively answer any question the other person may have. I will write a few short paragraphs detailing the following:
- What I’m trying to do.
- Why I’m trying to do it.
- What I’ve tried so far.
- Why each attempt has failed.
Here’s how I approach each of these sections:
What I’m trying to do
For this section, I try to keep the following in mind:
- Describe my intent in as much detail as I can, focusing mostly on the high level but delving lower where it’s necessary for the other person to understand the situation.
- Try to maximize the amount of useful information per sentence.
- Assume the other person knows a lot about the general field, but very little about my specific problem. If in doubt, I’ll err on the side of more detail, as it’s much easier for them to skip around rather than have to come back to me with a question.
- Try to describe more the high-level motivation behind the effort, rather than get too technical. For example, I will say “I am trying to add a new feature to my image host to recognize people in photos so I can blur their faces” rather than “I’m trying to use a Gaussian filter on OpenCV bounding boxes”. This allows the other person to steer me into a better direction, if the attempt I’ve made at a solution isn’t the best fit to my problem, and avoids the XY problem.
Why I’m trying to do it
Continuing from the previous section, I will go into a bit more detail about the why of the problem.
I will say something like “I had a lot of people asking me for an easy way to blur strangers’ faces in their photos”, to give them a better idea of the purpose behind what I’m doing. This gives the other person important background information on what I’m trying to do, and helps them form the context around the overall issue.
This section is usually fairly short, only one or two sentences, as the need is usually easy to describe.
What I’ve tried so far
This section is almost as important as the first one. The most important goals to keep in mind here are:
- Describe the things that I’ve tried, in as much detail as I can.
- Write up exactly what I did and the steps I followed.
- Show any relevant code.
- Explain my rationale behind each attempted solution.
This is important for two reasons:
- I’m showing them a few potential solutions, which means we can skip many things we already know don’t work.
- I’m showing that I’ve tried things and I’m asking for their help as a last resort, rather than lazily going to them immediately to get them to solve my problem.
Why each attempt has failed
Important goals here are:
- Describe in detail why each of the solutions I tried doesn’t solve my problem adequately.
- For every attempt, I will detail what I expected to happen, and what happened instead.
- Paste any relevant error messages or debug output.
Detail is very much appreciated here, because I know there’s nothing more frustrating than someone saying “it just doesn’t work” or “it doesn’t do anything”.
Done
When I’ve written all this up, I will send it to the person as an email or a wall of text somewhere, and let them get back to me at their leisure. If, at this point, they ask me something, it means I have failed to describe my problem adequately, and I should have spent more time clarifying my problem.
Usually, by this point they’ll have an answer for me. It’ll either be something I missed in my attempts, or some other alternative I can try, or a completely different solution that I hadn’t even seen.
I don’t want people to feel I’m running to them without trying things, or that I want to get them to solve my problem for me, and this process helps me a lot in soliciting feedback. It leaves people impressed at my preparation, and communicates to them that I do this work because I respect their time and appreciate that they’re spending it to help me.
As always, if you have any feedback or questions, please Tweet or toot at me, or email me directly.
