The stigma, “Just read the docs”, is a very common response to questions in software development.
What I think is really being said is, “Please show your work.” In high school, when I was taking calculus, my teachers taught me to show my work. I could get the wrong answer, but only miss 1 point because my teacher could see that I was on the right track.
Asking good questions is very similar to showing work on math tests to get partial credit.
Learning how to ask questions that show I’ve put forth effort has significantly improved relationships with my coworkers and the quality of answers I get.
Dealing with imposter syndrome
When I switched jobs from mobile development to backend, I felt completely inadequate in my abilities. Switching cold turkey meant that I didn’t know how to do… whelp… pretty much everything.
I had a choice at that time, ask questions or get nothing done.
I was worried they’d discover I didn’t know anything with backends and get mad. The truth, however, was they already knew that when they hired me. Of course, I’d ask questions about obvious things to them, they’d been working on backends for 5+ years.
What was obvious to them was not obvious to me.
Ask more questions
As I’ve transitioned to more senior positions, my number one complaint with coworkers is not enough questions.
I’ve worked for 5 different companies over the past 8 years and rubbed shoulders with 50+ engineers in that time. If you’re stuck, ask a question!
You’ve heard the quote or had a teacher tell you “There are no stupid questions”. I 100% agree, asking for help is the number one, easiest way to improve your situation. However, you can be doing yourself a disservice by asking bad questions.
There are such things as bad questions
Relying on my coworkers to help me perform can quickly be unsustainable. That’s why it’s important to ask a question the right way.
I’ve learned over the years that my coworker’s responses match the effort I put into my questions. If I’m lazy, I get a lazy answer. However, most of the time, I’m not trying to be lazy. In fact, I may have put in an enormous amount of effort. I just do a poor job of communicating it.
The best way I’ve improved my questions is by following one simple rule: Include context or as I like to call it, the effort log.
The Effort Log: Asking better questions
Whenever I’m searching for an answer to a question, I keep a mental effort log. The effort log becomes the precursor to any question I ask a coworker.
The idea is to record the things I’ve already tried to show that I’m not just being lazy.
It’s very tempting to think, there are way smarter people out there and I’m sure they already know how to do this. I’ll just ask. While true, there are many people out there and they probably know the answers, it’s unfair to them if I don’t include a log of my efforts.
Creating an effort log
My strategy for building an effort log changes depending on the category of my question.
An easy way to make an effort log is to use the 444 rule. I try 4 different searches, read 4 results, and spend at least 4 minutes (It actually is 5 for all of those, but the 555 rule was already taken, ha ha).
The type of searches I perform change based on the category of the question.
Different types of questions
Most questions I can google are lumped into programming questions. Figuring out the exact jargon to search for is perhaps what makes programming difficult at first.
The other categories deal with what happened in the past and what is happening in the future. Discovering why a decision was made carves out what requirements will be formed going forward. Both are common when I develop software.
Here’s how I apply my 444 rule to different situations.
Programming: 4 different google and/or code base searches
Past Context: 4 different places - git history, jira ticket, slack history, docs
Future Requirements: 4 questions and suggested solutions on how I think they can be solved
Committing myself to this effort protects my coworkers from me asking a bad question. So what does effort look like? Let’s dive into each situation a bit.
Programming questions
The minimal effort required before asking a programming question is to google it.
The search query is usually paired with “how to”, “is broken”, “not working”, “in javascript”, or my personal favorite, “<the error message>”. Occasionally I’ll include the suffix, “I’m super frustrated and mad”. Surprisingly it’s worked more than once.
Google is great, but that shouldn’t be the only place that’s searched.
I think one of the most underutilized resources for answers is the code base. Whether it’s the source code of an open source project or the code of a company I work at.
Glancing at the code often is the fastest way to solve a programming question. I can skip bad documentation and find ways other people have used the same methods I’m trying to use. Tests provide sample code of how to use a library and show it’s behavior.
Simply put, reading the code is a gold mine if google isn’t doing me many favors.
Past context questions
For a long time, I thought the only option to discover why decisions were made was to ask my manager or coworkers.
Questions like, “Why are there 3 endpoints to update customer addresses?” Understanding “the why” something was coded is perhaps the greatest software challenge. The person that wrote the code probably doesn’t work there anymore, their tests don’t cover edge cases, or there are hotfixes littered around that don’t have an obvious purpose.
But can I show effort before going straight to a coworker? The answer is yes! Simple things like git commits, jira tickets (trello cards, github issues, etc), Slack conversations are all ways to show effort before asking a question.
Git commits are supposed to include the reason why something happened (at least in theory). I’m guilty of having poor commit messages, but when I do have a good one it’d be something like, “Adding 2 more endpoints because customer X wanted to integrate with their internal billing system”. Context can also be record in a jira ticket linked in the git commit.
If I’m not lucky enough to have good git commits or links to jira tickets, searching Slack (or discord) is the next best thing. Linking to past Slack conversations is an excellent way to show I’ve at least tried.
Requirement questions
More often than not, designs, tickets, and issues lack specifics on what is supposed to be done.
In my experience, any simple coding task quickly balloons into a ton of tiny specific questions. Should the form behave like this? Is there a pending state? What kind of error message do you want the users to see? Can we do it faster, be more stable, add more features?
If I ask those questions when I immediately think of them (maybe every 5 to 10 minutes), I’ll quickly annoy my coworkers. I’ve found it’s important to intersperse my work with question checkpoints.
Since a lot of requirement questions are often mixed up with opinions, I always like to ask them with a suggested solution. As an example, “I noticed there wasn’t any loader in the designs, so I thought to include one like this. Does that look good to you?”
My coworkers really appreciate that I’ve put in some effort and aren’t just blaming bad designs or badly written tickets.
Ask a coworker (optional)
The beauty of the effort log is that it makes asking a coworker optional.
Going through the process often produces answers to my questions. Plus, writing out what I’ve already tried helps me work through my assumptions.
When I include an effort log in my question, my coworkers are way more willing to lend a hand. Making their job as easy as possible (including all relevant details) makes sense because when they help me they’re often leaving their own work to pile up.
Let’s look at what a question looks like when it doesn’t have an effort log.
No effort log
How do I concat two strings in python?
The answer from my coworker might be a link to the top result of google. Sometimes there’ll be no response at all. The really helpful ones will fish for what I’m actually trying to do. But they shouldn’t have to fish. I already put in some effort, I just need to include it in my question!
Same question with effort log
Context: I’m working on ticket #42 which wants me to combine two strings for an error message. I tried the answer from Stack Overflow <link>, but it’s not working for me.
Question: Anyone familiar with concating strings in python when dealing with error messages?
My coworker might chime in and say, “Oh I ran into this exact problem. Yeah, those error messages are really weird, try using our utils method to convert it to a string”
Put effort into asking questions
Having the effort log shows I’m actively trying to do something to help myself. It makes others more willing to help me. In a way, the effort log helps me do more than “Just read the docs”, it improves coworker relationships and produces top quality answers.
