How to Write Good Technical Questions: A Guide for Effective Collaboration
In a fully remote company like 7Factor, where Slack is the backbone for communication, the ability to ask good technical questions is crucial. Effective collaboration and clear communication are key to resolving technical issues quickly, avoiding project delays, and maintaining a culture where team members feel supported.
Why Good Questions Matter
Simply asking, "I have a problem. Can you help with A, B, C?" is too vague and lacks the information needed for others to provide meaningful assistance. Although your colleagues are willing to help, they may struggle to do so effectively without clear information. Unclear questions can lead to frustration and a sense of inadequate support within the team, misinterpretations, and wasted time. To ensure that your colleagues can help you efficiently, it’s important to follow best practices when writing technical questions.
The Anatomy of a Good Technical Question
These four points will help you craft effective technical questions. Let’s transform this vague question into one your teammates can easily answer:
"I’m running the app but I can’t log in. What’s wrong?"
1. Need
Describe the Problem: Start by clearly outlining the issue you're facing. This helps set the stage for understanding the problem and why it needs solving.
Provide Context: Offer relevant background information, such as the environment, code, or system where the issue occurs. This context is crucial for others to understand the scope of the problem. Think from the other person's perspective. How much context do you need to catch up to where you're at? Are they in this codebase daily, or have they never touched what you are referencing?
2. Expected Outcome
State Your Goal: Explain what you’re aiming to achieve. What should the ideal outcome be? This gives your teammates a clear target to aim for in their suggestions.
3. Actual Outcome
Show What Happened: Describe what happened when you tried to solve the problem. If possible, include visuals like screenshots or code snippets that illustrate the issue.
Include Error Messages: If you received any error messages, share them in full. These often provide vital clues that can help diagnose the problem.
4. What You Tried
Explain Your Attempts: Detail the steps you’ve already taken to resolve the issue. This prevents others from suggesting things you’ve already done and helps them understand your thought process.
Mention Resources: If you consulted any documentation, forums, or other resources, mention them. This shows you’ve put effort into solving the problem and helps others guide you more effectively.
Example of a Clear Question:
"I’m running the app locally. When I login with the username and password posted in our internal channel, I get a 400 error in the network tab. There’s a message in the console: ‘CORS header Access-Control-Allow-Origin missing.’ I’ve tried looking in the XYZ file, but I didn’t find the CORS settings there. Is there somewhere else I should look? Where should I find our CORS settings?"
Why Clarity Matters
Crafting your questions with clarity and focus is essential. It allows your teammates to quickly grasp the situation and provide help, reducing the time spent on back-and-forth clarifications. Additionally, thinking through your questions before asking ensures that you’ve exhausted all possible solutions on your own, ultimately making you a better engineer.
By following these guidelines, you’ll not only get the help you need faster but also contribute to a collaborative and efficient work environment where everyone can thrive.