Breadcrumbs and Troubleshooting

This week I'm taking a break from design patterns to talk about a useful skill to prevent you and your team having to reinvent the wheel when it comes to troubleshooting problems or working through new tools or frameworks.

Sponsor - DevIQ

Thanks to DevIQ for sponsoring this episode! Check out their list of available courses and how-to videos.

Show Notes / Transcript

Have you ever spent a few hours working through getting a new tool, library, package, or framework working? Along the way, did you run into things that didn't quite go as easily as the documentation, video, or presentation on the subject made it out to be? Did you end up spending time on Google, StackOverflow, etc. trying to figure out how to really get things to work in your real world environment? If you answered yes to these questions, you're in good company. I've certainly been there countless times.

Now, follow-up question. Have you ever done all of the above, but with a sense of deja vu, because you'd had to do the exact same thing some time previously? And when you found the blog post or sample that reminded you of the issue, you were like "Oh yeah, I had to do this last time, too!" I find these to be some of the most frustrating hours of my work. I want to be building things, making progress, seeing things grow in functionality, not banging my head against the same walls I've left dents and bloodstains on in the past. I also want to make sure my coworkers, my teammates, and my clients benefit from the cuts and bruises I acquire as I blaze a trail through unknown territories. So, what can you do to limit the amount of retreading through through the same painful terrain you (and often your team) have to do?

Obviously the first thing you could do is take notes. This is natural for some developers, but others find it distracting. When they're in the zone, figuring things out and getting things done, they don't want to stop to document things along the way. Breaking their flow might mean the difference between getting things working and giving up and walking away. If you can take notes, do so. I suggest keeping track of the URLs you found useful, along with screenshots of things like property settings or other configurations that you needed to modify to get things working.

Sometimes, you can document things after you got things working. This is often true for fairly simple problems. However, for something that's taken hours rather than minutes, it's likely that by the time you're done, you've forgotten a few steps along the way. Here are a few things you can do to leave yourself a trail of breadcrumbs as you work. And of course, by breadcrumbs, I actually mean something better than breadcrumbs that you'll actually find later, since the whole origin of breadcrumbs is from a story in which breadcrumbs are a decidedly poor choice to leave behind you in order to find your way.

One approach I use is to use a particular browser instance while I'm working on a specific problem, and to open all links related to the problem at hand in their own tabs. If they're useless, I close them, but if they're at all helpful, I leave them open. Once I've figured out whatever it is I've been working on, I can look at my tab history and add the links as references wherever is appropriate. Sometimes that's a link in a source code file. Sometimes it's in a README file. Sometimes it's in a blog post (or a Trello card for a blog post I want to write). In any case, I associate the links to the resources that helped me along the way with the problem I just solved while everything is still fresh in my mind and the links are literally stil open in my browser.

Another tool you can use is screen recording. If you don't like actually writing/typing notes, you can record conference calls with clients using tools like Zoom or GoToMeeting. You can also record your own screen using tools like Camtasia, which I highly recommend. Then you can quickly jump around in the video to see yourself tackling problems, and retroactively make notes or write up a postmortem or checklist. Occasionaly the video itself might even be worth editing into something, perhaps for internal consumption by your team.

Yet another tool I've used in the past is TimeSnapper, which would take and store screenshots every so many seconds on your machine. Then it would let you play them back later to see what you'd been spending your time on. I haven't used it in a while but it appears to still be active. You could do something similar by just taking a screenshot periodically as you progress through a problem, but you're much more likely to forget without a tool like this.

The most important thing to take away from this episode is that you don't want to fight through the same problem more than once. Ideally you want to prevent your team from having to fight through problems you've already solved. The key is to share the necessary information in a way that doesn't slow you down while you're solving the problem, but which ultimately is discoverable by you and your team the next time you encounter the same problem. An approach I've used for years is to blog about things once I find a solution. I can't tell you how many times I've googled for something only to find the answer on my own blog. If you have your own techniques you use to rediscover solutions to problems you've previously solved, please leave them in the comments for the show.

Oh, and I wrote an article last year on Working Through Roadblocks - A Guide for New Programmers. I'll leave a link in the show notes for that as well.

Would your team or application benefit from an application assessment, highlighting potential problem areas and identifying a path toward better maintainability? Contact me at ardalis.com and let's see how I can help.

Show Resources and Links

• Camtasia
• TimeSnapper
• Working Through Roadblocks - A Guide for New Programmers