Syntax Error #10: Debugging knowledge base

Happy holidays! The end of the year is approaching fast and for me personally, it means spending time with family celebrating Christmas and taking a look back at the current year and wrapping it up.

A personal thank you for being a reader ❤️. A year ago I was sitting in a hotel room in Prague while participating in DevRelCon and I came up with an idea to start writing this newsletter. A year later, there are 206 of you subscribing via email and many more who subscribe via RSS or read these posts on the website.

Advent of Code

December also means I've been busy with Advent of Code puzzles that I solve with Python and share my solutions with explanations on my personal website. If you're not familiar with Advent of Code, let me get you in on the secret: it's a fun 25-day puzzle calendar with lovely Christmas lore and interesting puzzles to be solved. Each day, you'll get a puzzle in two parts and you need to solve it by any means necessary: usually people choose to write code.

Often you make small mistakes so it also offers good practice for debugging. The state of your program is so large it's basically impossible to inspect by hand all at once. This leads to learning good spots where to get your tools out to make some sense of the whole. And you end up debugging something almost every day so the repetition makes good practice too.

"The best debugging tool is knowing something well"

In a great talk Now and Then Debugging Async JS, Jenn Creighton has this quote: "The best debugging tool is knowing something well" and it's been marinating in my brain ever since I saw it. (Although in my opinion, print is the best debugging tool.)

I recommend watching the entire talk if you're writing any asynchronous Javascript ever.

The quote packs lots of wisdom: we become more efficient in debugging and recognizing certain issues because we've encountered them many times before. It got me thinking: how could we use this to our advantage in teams by building shared understanding of debugging situations.

Build a shared debugging knowledge base

What follows is a thought experiment that I've been thinking about lately. It's not based on something I've (yet) had the opportunity to do but I'd like to do in the future. I'd love to hear your opinions on it and what you'd change, add or remove to make it work. And especially I'd love to hear if your team is already doing something like this! Hit that reply button and let's chat.

Step 1: Keep notes of debugging

First step is to start keeping notes of the moments when you debug. Have some post-it notes, a paper notebook or a virtual note-taking tool with you when you code. Then, whenever you run into a situation where you need to debug, write a few short notes about it: what was the issue, how did it show itself, what were you thinking, how did you solve it and how long it took to figure it out. It doesn't have to be an essay but rather a few short lines.

Step 2: Regular knowledge sharing sessions

Does your team share knowledge amongst the team regularly? I've noticed it's surprisingly rare despite the fact that we work in knowledge industry where we collectively know a lot of different things but still need to build that practical knowledge individually all the time.

In one of my previous jobs, we hosted weekly Tech Weeklies sessions every Friday. For one hour at the end of the week, the developers would come together to share knowledge, usually in form of 20-30 minute talks. The topics ranged from very practical to weird but interesting. I loved that culture of sharing. And even when you didn't learn everything that was shared, you'd gain knowledge of who of your colleagues know about different topics.

The first thing is to start running these things. And then the next is to use some of those to share stories about debugging based on the notes you've taken. This is especially helpful when done with the team members who work on the same code base or part of code base since it's likely they'll run into something similar.

Step 3: Collect the notes to a shared knowledge base

Creating a good, searchable knowledge base is a billion dollar problem but while we wait for that to be solved, it's still worth trying.

So collect those notes from all the developers into a space that can be searched. Use tags and keywords to categorize individual debugging notes. Because search is such a hard product problem still to be solved, I think the combination of notes in a shared place and the sharing sessions to let people have memory of what issues have been encountered is the key at this point.

The sharing sessions create memory traces to your brain. When you run into a problem, you can think back to those sessions and see if you remember something similar. And then you can dive into the knowledge base to find the details.

Like any good knowledge base, it will take time before it becomes powerful. But my hypothesis is that it can save a lot of time down the line with relatively small effort of taking notes. Not only will it save time when debugging happens but it also builds a larger understanding of things that end up becoming issues so we become more likely to not create them in the future as well.

I do however understand that "taking notes" is a habit that I am more into than some other people so it is possible I'm underestimating the effort it takes to make those notes.

Sidenote: Incident reports and post-mortems

While I haven't heard anyone do this kind of thing for debugging, I've found a lot of teams do it for larger incidents with incident reports and post-mortems. They come together, write a good document and sometimes they are hidden, sometimes searchable.

So if you're doing those already, see if you can get into a habit of making similar, yet much smaller notes about your debugging cases.

Story time

Today's story comes in two Youtube videos. Nathan Baggs wanted to play an old Worms 2 game online so he looked into reverse engineering the networking protocol of the game. The videos are Fixing Multiplayer Of A 25 Year Old Game and Hacking a 25 Year Old Game To Make It Work and I really enjoyed watching them.

He does a great job explaining his tools and approach to reverse engineering what happens when you press the button to connect to a server. One of those tools being "If I send a bunch of As as a response, I hope it crashes and we can learn from the crash report". Sometimes you gotta do what you gotta do.

I really liked this quote from the second video:

When I get stuck like this it's useful just to take a step back and ask myself: what do I actually know? And that is, pressing a button fires and event with an id and the id determines which menu it renders. So where does that id come from? That seems to be the key to this puzzle.
[ - - ]
The real prize is the breakpoints we set along the way.

Syntax Error is created with love by Juhis. If you liked it, why not share it with a friend? Or if you have any feedback or just want to say hi, hit reply. I'm always happy to hear from my readers and learn about what you do and how you debug your issues.