33   Keep a Solutions Log

“Do you often get that déjà vu feeling during development? Do you often get that déjà vu feeling during development? That’s OK. You figured it out once. You can figure it out again.”

Facing problems (and solving them) is a way of life for developers. When a problem arises, you want to solve it quickly. If a similar problem occurs again, you want to remember what you did the first time and fix it more quickly the next time. Unfortunately, sometimes you’ll see a problem that looks the same as something you’ve seen before but can’t remember the fix. This happens to us all the time.

Can’t you just search the Web for an answer? After all, the Internet has grown to be this incredible resource, and you might as well put that to good use. Certainly searching the Web for an answer is better than wasting time in isolated efforts. However, it can be very time-consuming. Sometimes you find the answers you’re looking for; other times, you end up reading a lot of opinions and ideas instead of real solutions. It might be comforting to see how many other developers have had the same problem, but what you need is a solution.

To be more productive than that, maintain a log of problems faced and solutions found. When a problem appears, instead of saying, “Man, I’ve seen this before, but I have no clue how I fixed it,” you can quickly look up the solution you’ve used in the past. Engineers have done this for years: they call them daylogs.

You can choose any format that suits your needs. Here are some items that you might want to include in your entries:

• Date of the problem

• Short description of the problem or issue

• Detailed description of the solution

• References to articles, and URLs, that have more details or related information

• Any code segments, settings, and snapshots of dialogs that may be part of the solution or help you further understand the details

Keep the log in a computer-searchable format. That way you can perform a keyword search to look up the details quickly. Figure 6, ​Example of a solutions log entry, with hyperlinks​ shows a simple example, with hyperlinks to more information.

---

Figure 6. Example of a solutions log entry, with hyperlinks

When you face a problem and you can’t find the solution in your log, remember to update your log with the new details as soon as you do figure out a solution.

Even better than maintaining a log is sharing it with others. Make it part of your shared network drive so others can use it. Or create a Wiki, and encourage other developers to use it and update it.

Maintain a log of problems and their solutions. Part of fixing a problem is retaining details of the solution so you can find and apply it later.

What It Feels Like

Your solutions log feels like part of your brain. You can find details on particular issues and also get guidance on similar but different issues.

Keeping Your Balance

• You still need to spend more time solving problems than documenting them. Keep it light and simple; it doesn’t have to be publication quality.

• Finding previous solutions is critical; use plenty of keywords that will help you find an entry when needed.

• If a web search doesn’t find anyone else with the same problem, perhaps you’re using something incorrectly.

• Keep track of the specific version of the application, framework or platform where the problem occurred. The same problem can manifest itself differently on different platforms/versions.

• Record why the team made an important decision. That’s the sort of detail that’s hard to remember six to nine months later, when the decision needs to be revisited and recriminations fill the air.