What? Why?

We've (probably) all been there: you're dealing with a simple bug or production alert and you're racing to just figure it out. You might be lucky - have a hunch, jump straight into the code, find the cause and quickly prepare a fix.

Alternatively, the same approach gets you nowhere and you quickly hit a wall...

With no hunch to go off, you don't know where to start and your brain goes into overdrive. You go to ask for help from your colleagues, but your approach can best be described as a tangled mess in your head; you end up spending time starting from scratch. Chaos ensues.

A systematic approach

One framework that I've found works well for me is using the "What? Why?" cycle - an approach that encourages you to systematically investigate issues and ask the right questions. This mindset aims to avoid assumptions and ensures you're working with reality and not haphazard guesswork.

What?

The first step is to clearly define what is happening.

Always start by creating an investigation document - this works great in many folds, the two main being:

1. Forces clarity of thoughts
   • Great when you're dealing with a system that has multiple components and layers of complexity
2. Easily shareable
   • Useful when asking for help - colleagues can see what you've tried so far
   • Serve as a source of truth for incident updates - you're pushing updates out into the open

Gather all the evidence you can: telemetry, user reports, stack traces, screenshots, configurations.

If you can reproduce the issue - document how. It's also worth figuring out whether it can be reproduced reliably.

Describe what's broken - the reality is, you can't fix something if you don't know what's broken.

Why?

Now that you have a clearer idea of what you're looking for, you're far better armed to trace the cause and figure out why it's happening.

This is where critical thinking comes into play. Debugging is in effect a scientific experiment. You'll want to keep asking probing questions, form a hypotheses based on evidence, and then test your theories until you figure it out.

Useful helpers

Divide and conquer

Complex distributed systems can be overwhelming - use the divide and conquer strategy to break it down into manageable steps.

Narrow the scope of your search by isolating components and identifying which part(s) of the system are responsible for the symptoms.

Iterate with the "What? Why?" cycle for each subsystem and piece of evidence gathered until you pinpoint the root cause.

Keeping an investigation document

Your investigation document is your best friend both during and after the investigation. As well as forcing clarity of thoughts and being shareable, it shines in a few of other ways:

1. Reflection and post-mortem's are easier
   • Self-reflecting on the approach taken and identifying any patterns to your debugging approach will help you continuously self improve
   • Deriving a clear action plan for product and observability improvements
2. Knowledge sharing
   • A well thought out product shouldn't be hitting these sorts of issues frequently, so there's often not a lot of opportunities to perform such investigations
   • Sharing spreads the knowledge - so you don't necessarily need to be dragged in the next time something similar occurs
   • An opportunity to showcase technical depth
3. Document bonus issues you find along the way
   • Sometimes you find issues which aren't related to the main problem at hand, you can easily make a note and then continue back to your investigation.
   • This demonstrates ownership and understanding

Conclusion

Debugging isn't just about fixing bugs - it's about understanding systems and asking the right questions.

By applying structure and a systematic approach to debugging with the "What? Why?" cycle, you'll likely solve problems faster but also grow as an engineer.

Next time you feel like you've hit a wall - try this approach and let your curiosity lead the way.