Keeping a NOTES file

Sometimes on a project, it feels like everything just flows. The ideas turn into code, the code works properly, it solves your problems and then you hit commit and go to the beach. Unfortunately, especially for more interesting projects, you tend to spend a lot more time being stuck. The key observation to blow this whole thing wide open is just around the next corner, but until then you just bang your head against it and feel dumb.

The best solution I've found for getting over that wall is to talk to someone about it. Unfortunately, using a real person is fairly limiting. Firstly, they have to be familiar with the project, or you have to explain the project to them in enough detail that your problem will make sense. Secondly, in most cases the person you use won't get that much out of it. You're talking for your own sake, not theirs, and ultimately that makes it unsustainable.

The state of the art, then, is Rubber Ducking. That's when you explain your problems to an inanimate object (like a rubber duck) instead of a person. You can assume your rubber duck has good domain knowledge (rubber ducks are notorious generalists), explain the problem whatever way best helps you, and have your epiphany safe in the knowledge that the rubber duck is really chill about just being a means to an end.

But there are a few issues with talking out your problems that even the mighty duck can't solve. Some people think better in writing than speech. Some problems don't translate well verbally, especially very structural ones. And worst of all, talking doesn't persist anywhere. I find myself running over the same ideas again later on and questioning my reasoning, or coming back to a project after some time away from it and not remembering what I'd decided.

My attempt to solve this, in the great unix tradition of all-caps files like TODO and README, is the NOTES file. When I get stuck, I just open up a NOTES file in my editor and start free-form writing about what I'm stuck on. Sometimes that looks more structural (lists of ideas, example syntax, comparing various API designs) and sometimes it looks more like a self-directed Q&A: "what about X issue?" "how do you solve that while still keeping Y?"

I've found this uniquely helpful. If it doesn't outright solve my problem, it often clarifies it to the point where I know what I need to do to solve it. What's more, I find the NOTES file acts as a great starting point the next time I come back to the project. The latest text makes great background reading so I can get immersed in it again quickly.

If you're stuck on something, I highly recommend giving a NOTES file a try. Worst case scenario, you've accidentally written some documentation.