Programming journal - helps me get things done

My journaling technique is the best thing I use that makes me way more productive. This is how it looks now:

Simplicity

As you can see, it’s very simple, but it works very well. Simplicity makes me stick to it.

It was hard do in the past. I was using advanced apps (like Logseq) with nested structures and links… But now I just use a file. In practice I found that advanced formatting and structuring doesn’t solve any problem, but requires additional mental energy to do.

Ergonomics matter

I deliberately keep the file in the project as part of version control, so it’s as close to my code as possible and it’s just a shortcut away in VS Code. The more convenient it is to open - the more I will love it.

Git history

I actually commit my journal file. And every month I cut all the entries for the month in a separate monthly archive. That way I can sometimes go back and get a fee of how I was doing previous month.

Satisfaction

Journal makes me feel good. And makes me feel my productivity. I just write the task, do it, commit, and check it off ✅. It’s an extra dopamine spike that I feel great about. Now I cannot go back to working without the journal anymore.

Also archiving the entire month of journal makes a very good feeling. It’s something similar to collecting books or writings. You look at the archive and literally see how much you wrote. It maybe sounds dumb, but it’s very important. We humans are dopamine-seeking creatures.

Advanced debugging

When I find a really nasty bug, the journal helps me write down steps I took to try to reproduce and fix it. I can literally write the experiments I’m doing. This 1) makes it faster to solve and 2) if I couldn’t solve it, it’s easier to ask for help, because I already have written down what I tried to do.

Direction for the mind

I know my brain wonders around a lot. When I work, sometimes I can get astray to some refactoring, or other nonsesne that doesn’t matter right now. So I discovered that when I write down what I’m trying to accomplish, sometimes even I forget that - i can go back to the journal and remember what exactly I’m doing.

This is incredibly useful tool to direct my mental focus to the very specific task. It can’t be overstated how incredibly powerful, useful and yet simple it is.

Save point

And the best thing? I can get disturbed, then come back to work and I know exactly where I stopped. I don’t have to keep the entire context in my head anymore.

They say Abstractions let you not worry about implementation details(which they are not), but the journal actually frees my mind a lot, and I have more space to solve actual problems.

Self reflection

This is really vague, but I have a feeling that it’s the most important point. Writing journal makes me reflect on what I do well and where I can improve. Why bugs pop up, what approach I did wrong, etc. It’s helping me be aware of my work on a meta level. You can only see this when you do it yourself.

Prefix makes it really clear

I use prefix to say what part of application I’m working on. It helps me understand the message itself, when I see the prefix, I can better understand what the message is talking about.

I also can get a general feeling of what parts of application took a long time. Especially when looking in the monthly archive.

Adjust granularity to your needs

I find that when I’m doing something I’ve done many times, and nobody is disturbing me, there is no need to write a lot of journal. I can keep entries fairly high level.

On the other hand, when I’m doing something I’ve never done, I may write very granular entries in the journal, it helps me move forward since I’m unsure of every next step.

---

People asked some questions, so I will post my answers here:

Q: How is journal different from a todo-list?

A: Journal starts as a todo-list, but then gets added journal entries as needed. Let me explain.

Let's say I want to add user-edit functionality, so I write:

-- TODO 18.06 [user] edit backend endpoint

Then in the process of doing that, I find either a) some problems that I need to debug or b) just want to clarify in more details what specific parts I'm doing - to "direct" my mind in a specific section of code (before getting distracted for example). So I write additional entries before the initial entry

So the next snapshot of the journal will look like this:

-- TODO 18.06 [user-settings] add validation to the page

-- TODO 18.06 [user] edit backend endpoint

So on the bottom I always have the 'todo' item, and at the top I have additional 'journal' items which are more tiny, more specific baby steps towards my todo.

---

Q: How do you deal with long-form text in the journal?

A: Long form text yeah, it's not very convenient, but I rarely have it, because usually I split stuff into tiny todos. And when I do have it, it doesn't really bother me, because nobody looks at the journal except for me.

This is how it usually looks like:

---

Q: How do you get a clear high-level overview from the journal?

A: I don’t. The journal is not designed for that. It does different job and does it really well, but it’s not suited for other different tasks, and that’s okay I guess.

---

I hope you find it interesting and try for yourself.

The journal technique is one of many tiny things I discovered when I started building my startup (AMS Pilot). I put a lot of pressure on myself to finish the project the best way I can and in the shortest amount of time.

I will try to write down other techniques as well. Some of them are very weird and unconventional, but I don’t care. What I care about is the end result - quality software and happy users.