I’m currently in the midst of a substantial Kubernetes migration project, and the other day, after a messy merge, an error came up that I’ve definitely seen before.
I remember solving it, but as time passed, the solution slipped away from me. I couldn’t remember what did the trick. Well, I bet git will tell me.
Scrolling down the history log did highlight a few attempts to solve it, but nothing too specific.

So how do you deal with errors and issues during your work? What is the best way to document them? These are not necessarily documented bugs that your QA team or automation processes caught, but the stack traces, exceptions, and errors you deal with during development.

Here are a few things you can help future you:

1. Add the errors to the git commit message

Create the habit of pasting in the error message / Exception / Stack Trace into your git commit messages.
It’s simple, and the value is right there - you can search for the error and view the solution right there in the code. Really, there isn’t much to it.

2. Take the time and create an issue

Good idea! And/or creating an issue with the full details of the error, and making sure to reference the commit to it (ie. adding “Refs #123” to commit messages for github issues)

— Brian Hogg (@brianhogg) February 16, 2020

You can help your team by creating an issue in your bug/ticketing system, describing the full scenario and link to the git commit.
It has more visibility and allows for discussions - someone may have a better view of things and may direct you to a better solution.

3. Keep a Development Journal

I like to keep, at the least, an open markdown (never did manage to pick up org-mode) file to keep notes during development. For me, it tells the story of why I did things in a certain way, and the writing process forces me to think before committing to things.
It’s also a great place to keep short notes, errors, and things you struggled with for future reference.
Later on, you can use these entries to create project documentation or defend your solution.

In any case, this is another excellent place to document errors, allowing you to understand the full story behind the issue.

4. Write a blog post

Even better, you can share your solution with the world. There are still so many non-documented errors that, at best, show up in a long and still open git issue thread.
The post doesn’t have to be long as long as you have a searchable error and a solution.

5. Answer Stack Overflow questions

I’ll admit that I can do much better at this, but often, such issues are posted as open questions on Stack Overflow. Sometimes there is an answer, but your use case is not 100% similar, and nothing works. By the time I do solve the issue, I have a million open tabs, and I forget to write down the answer for what worked for me.

Be a better community member than me and post answers on Stack Overflow.