For a while now, I have kept a journal of my programming related activities. I find this to be good for three things:

  1. I pour out all my thoughts about a problem I am solving, or task I am doing, and this helps me think more clearly. The act of writing requires me to think things through. When I write like this, I write to a future self, who is angry and digging in the journal to find out why I did the stupid thing I did. Sometimes, if I explain my reasoning, I realize while writing that I am doing a stupid thing. Other times, my future self will realize that my reasoning was sound, but something happened to make it stupid later. In a more social setting, I could discuss things with a co-worker to get the same benefit.
  2. I write down steps to do specific tasks, which is sometimes helpful when I need to do them again, or when I need to figure out what broke.
  3. If I am hacking on some code, and need to take a long break (for example, to drive from Christchurch to Wellington via Auckland), I can more easily pick up the work again. My journal will tell me where I was, and what I was thinking.

I do not keep the journal as regularly as I wish I would, but even when I update it only half the time, it is quite useful. When you can’t walk, it helps if someone carries you, even if they only carry you half way.

I started this journal on November 3, 2005, using a single plain text file. Eventually that grew too big to be practical, so it became a series of text files instead, one per day. For a while the files were in HTML, but that was tedious, so I switched back to plain text again. Now, I use ikiwiki and markdown.

Markdown is a wonderful, minimal markup language. Almost all of my journal entries from the plain text era were already in markdown, perhaps with minor tweaks. When I need more power, I have it, but when I don’t, I do not have to do suffer from the tediousness of writing HTML by hand.

Ikiwiki is a wonderful wiki engine, which is quite flexible. It can use a real version control system to store the wiki contents. With modern distributed version control systems, this gives the additional possibility of having multiple instances of the wiki. For my journal, this is useful: I can have the same journal on my laptop, for personal projects, and on my work machine, for work stuff. Having the same journal on both places makes it easier to look things up.

I could keep the journal on a server, of course, and access it over the Internet. That is what I would do, if I had good Internet access everywhere, but I don’t.

Using a good wiki engine for the journal has proven to be quite useful. I can use tagging to make it easier to see journal entries for specific topics. Ikiwiki uses the xapian search engine to provide handy full text searches.

I am also experimenting with a feature to have wiki pages for people I mention in my journal entries. Each person has a dedicated page (/person/wirzenius.lars), and each entry that mentions that person, links to their page. The page then uses ikiwiki’s inline directive to automatically list all journal entries that mention them.

This makes it much easier for me to remember who the people are, for people I meet rarely. There is something wrong with my brain when it comes to remembering people, and I need every bit of help I can get.

I may expand this to other things than people, some day, but I need to be careful about not making it too tedious, or I will stop keeping the journal. Full semantic web markup is not going to happen.