I started my career in Open Source Software. A sizeable portion of the contributors are geographically distributed and are volunteers. To accomodate them, a great deal of focus is on asynchronous communication and documentation. People respect each other’s time and are mindful of the same while asking questions. As an active member of these communities, I observed people practice a few techniques to effectively communicate asynchronously. Tips and trick I had picked up have also helped me tremendously in my day job.
I wrote down key learnings last year, for an engineer I was mentoring, to help them get better at communication. I am publishing this externally in hopes that other people might find it helpful as well. Whether its on slack, mailing list, github comments or a community forum, these tricks will help you ask questions effectively across all mediums!
Have a friend who makes your phone go buzz, buzz, buzz with 10 messages all sent within a span of a minute? Don’t be that person professionally. Don’t bombard someone who you’re asking for help with a slew of messages. No one appreciates distraction, especially on Slack.
On the flip side, don’t also be that person who just sends a “hey!” and waits for the other person to get back before jumping to business. People are preoccupied with their work, if I'm gonna interrupt their train of thought, I better make it worthwhile, instead of just sending an ambiguous greeting.
Instead, craft your question, with all context and relevant links in a single message/email/comment. A single message is enough to convey the problem you’re trying to solve. The best way to make the question comprehensible is to break the block of text into bullet points to make the information glanceable. If its too much text to fit into a single message, start a thread and post all relevant information in that thread.
Chances are other people (both present and future) might also have the same question. Asking questions in a public forum, whether it is a public slack channel or group email thread, enables multiple people to answer your question. This gives you a wide range of opinions and also you're not blocked on a single person to answer your doubt. This will also make the conversation searchable for later reference, both for you and other people.
Software engineers are infamous for overusing “it depends”. Though its often joked about, reality is solution to a problem does depend on the context it is being solved in. Its easy to assume one size fits all, but in engineering thats hardly ever the case.
This makes its essential to give complete context about the problem you’re trying to solve. Add approaches that you tried but didn’t pan out. Add links to StackOverflow questions/articles/blogs you’ve read which gave you a better understanding of the problem. Giving enough background information better equips the person to answer your question correctly and swiftly. You'd be surprised the number of times just writing down everything clearly will lead you to the answer yourself!
When a person takes out time to answer your question, they are context switching from their work. Its your responsibility to ensure this time is the least.
Apart from practicing the above, respecting people's time also means:
As William Zinsser says in On Writing Well, Simplify, Simplify. You don't wanna write a page for what can be expressed in a sentence. Keep editing you message till its stripped of every non essential sentence/word. Succinct and to the point should be the aim. Some easy tricks for this are:
Lastly, this is an excellent resource on how to write professionally.
The worst way to irate a software engineer is to ask them an obvious question. It shows you didn’t do any due diligence and don’t have respect for their time.
Always, always, always research your question before putting it forth. This means use Google or even ChatGPT these days, go through relevant StackOverflow questions, search for the answer in your organisation’s internal docs (if you’re working in a remote first organisation, chances are there is a strong culture of documentation) or even comb Slack to see if someone has already answered the same question in the past (you’d be surprised how many times that actually works!).
If you don't do the prerequisite research before asking a question, don't be surprised if you're hit with one of these (depending on the engineer’s mood):
First, what even is the XY problem? From here,
The XY problem is asking about your attempted solution rather than your actual problem.
That is, you are trying to solve problem X, and you think solution Y would work, but instead of asking about X when you run into trouble, you ask about Y.
Software engineers tend to get caught up with this often. It can take a lot of back and forth before you communicate the actual problem you’re trying to solve. The best way to avoid making this mistake is to give a 1000ft overview of the problem you are trying to solve. Again, providing proper context always helps.
Have you come across questions like these?
Hey friends, does anyone have experience with Golang?”
“Hey, do you mind if I bother you with a question?
This one generally happens unintentionally. You think you’re being polite before bombarding someone with a question, but really its just adding one more round of back and forth. Instead, craft your question and just send it over! If they can’t help you with it, they’ll probably let you know or guide you to someone who can, and if they do have the bandwidth to help you out, they’ll just respond with the answer. In either case, you’re getting an actionable outcome. You can read more about this here: https://dontasktoask.com/.
Your peers will actually want to answer your questions if you follow the above steps. While it may seem overwhelming, as you keep practicing it on a daily basis with every question you ask, these things will become a habit that won’t require an extra effort from your end!
Please do reach out to me on mail or on twitter if you found this helpful, that'd make my day!