↓Skip to main content

Solution notes: stop repeating past mistakes 📝

#collaboration

Lineart illustration of a man falling down a rabbit hole
Have you ever solved a problem, only to face it again six months later—familiar, but with no memory of the solution?

Then you may want to write solution notes: short, searchable records of problems and their fixes, helping you avoid the frustration of going down the same rabbit hole again.1

Anatomy of a solution note #

A solution note consists of three parts.

The problem #

First clearly document the problem. Include the exact error message and other symptoms. Mention the application that reported it. Include context such as what you were trying to achieve, if relevant. Ensure that the description makes the note easy to search for next time you encounter the error.

Skip notes for trivial problems. If the answer is instantly searchable, save your energy for harder ones.

The cause #

Figure out why the error occurs. Then document it.

You might be tempted to skip documenting the cause once you have a working fix. Don’t. Recording the cause helps you understand systems better, improves your troubleshooting skill, and builds the mindset that all problems can be understood.

If you find the solution before the cause, write the solution first but don’t forget to go back to figure out the cause.

The solution #

Finally, document the solution to the problem.

Some solution notes may be very specific to your setup or situation, but if they are not, share them with your team.

An example #

To give a feel for what they may look like, here is one from my own notes.

Azure: At least one certificate is not valid #

Problem #

When trying to upload new TLS certificates for a domain, Azure rejects a valid .pfx certificate file with an error:

At least one certificate is not valid.
(Certificate failed validation because it could not be loaded).

Cause #

Azure requires keys to be signed with 3DES, but OpenSSL 3+ no longer uses 3DES by default.

Solution #

Adding the -legacy option to the openssl command reverts to the old default behavior. The certificates generated with the -legacy flag are accepted by Azure.

Next time you stumble upon a problem, spend a few minutes to write a solution note—your future self will thank you.

  1. You may also be interested in architectural decision records (ADR) and today I learned (TIL) notes. ↩︎