Software engineering encompasses more than just writing the code; it often involves troubleshooting various problems. I find myself deeply connected to and enjoying this “problem-solving” aspect, often receiving questions from less experienced colleagues and friends like, “How did you find the solution to the issue?” Reflecting on and observing how others tackle problems has taught me a crucial insight: clarity of thought and eliminating distractions are key to success.

Below is a simple mind model that I regularly employ. I find it especially valuable for conveying ideas effectively, considering that communication is frequently the most daunting aspect of our lives, especially when multiple individuals are engaged in the troubleshooting process.

Everything starts with the problem, so:

• The problem must be clearly defined: What exactly are we trying to solve? Why is this an issue and not expected behavior? Understanding the context and specifics of the problem is crucial. Typical examples include: “Service X is down“, “Feature Y is not functioning as intended” or “Performance of system Z has degraded”.
• Evidence and observations: Present verifiable facts that support the existence of the problem. These facts should remain objective and devoid of emotion, focusing solely on the evidence at hand. This can range from specific occurrences like errors in logs to failed test cases in the pipeline or huge spikes on memory consumptions dashboards. Concrete evidence helps pinpoint the issue and guides a focused troubleshooting process. Having more observations if always better than less.
• Assumptions: Clearly state any assumptions made. This step is often challenging as it determines which assumptions are relevant to the issue. Common examples include: “There have been no recent software changes“, “There have been no alterations in user behavior” or “Previous pipeline runs were successful“. It’s crucial to articulate assumptions clearly, as they form the foundation of the problem-solving approach and can reveal overlooked factors. One effective way to assess assumptions is to ask yourself: “Is this assumption always true? Why?” Often, the most elusive bugs stem from the simplest assumptions, such as “our computations are deterministic” or “this code is thread-safe“.
• Conclusions: Clearly outline how conclusions are drawn from the evidence and assumptions. For instance, if the problem could manifest at levels A, B, or C, and evidence shows A is functioning correctly while assuming B is also operational, then focus shifts to level C. Conclusions may indicate insufficient evidence, necessitating further data gathering, or flawed assumptions, prompting a reassessment and revision. Clearly defining conclusions fosters a logical and methodical approach to problem-solving.
• Finally, iteratively revisiting steps above allows us to progressively narrow down the problem to a specific sub-issue occurring at an atomic level. This systematic approach enhances our ability to debug and hence resolve the issue.

I hope this brief write-up proves beneficial.

Feel free to try this structured approach next time you encounter a troubleshooting challenge.