21st Century Journaling for Developers

Why even journal?

I can't make you start journaling regularly but I would like you to at least consider this amazing habit that you might have been missing out on.

Personally, I journal every day because my mind often feels like a jumbled mess and taking things out onto a structured format helps me organize myself and my day. I have had times when I had to face complex thoughts and emotions, for most of my life I advocated just sitting down and thinking things through but it didn't always suffice.

This article is aimed at developers only because of the proposed solution. Just as you might not be able to model entire programs in your head, so it is for the mind. There comes a point where software becomes complex enough that you need other tools to reason about it, same goes for the mind which could arguably be considered as complex software.

What does the right journal need?

When I started journaling I used whatever pen and a booklet I had on hand. It actually worked great as an unconstrained medium to write in but there were logistical problems. Booklets started to pile up, it was impossible to accurately locate an entry, and to be honest my handwriting is horrible, especially when trying to write at the speed of thought.

I then moved to using Google Docs but that required internet an connection and too many steps outside of my workflow to get started. My last attempt was to use a dedicated journaling app for Windows called Glimpses. That one worked great for a very long time and really cemented my journaling habit but eventually it failed. It had some issues with syncing and I always had to boot back into Windows to write.

The dev life

My journaling needed the kind of flexibility I had with pen and paper while still being highly structured. My first thought was to make my own program but I never got around to it, instead I found a tool to which I added more tools, and now I have a veritable tool belt that hits all the nails:

• Cross platform (Linux/Windows)
• Flexible
• Easily insertable into my current workflow
• Minimalistic
• Upgradeable and extensible

I found this in an open source terminal application called jrnl, paired with a few aliases, Vim (or whatever you want), and many plugins, it's as close to perfect as I've found.

The case for Bash

When I first started using Linux, I found the terminal to be an archaic and clunky option that never really understood what I wanted to do. Today when I boot into Windows, the thought of actually navigating the explorer with a mouse gives me shudders of inefficiency.

Now, the first thing I do in Linux, is open a terminal and check for updates, it's a reflex, a habit, and thus the best place to add another action.

Now, I log in, check for updates, open another terminal and start journaling as they run.

Here's how you can set this up for yourself.

Install jrnl

Go to their website and follow their installation instructions, if you are installing jrnl with pip and it doesn't work, do not use sudo, instead try with the --user flag.

Once that is done we have a few config files to work on.

jrnl Config

In your home directory create a file named .jrnl_config. If you are on Windows place it at C:\Users\[Your Username]\.jrnl_config.

In it place the following:

.jrnl_config

{
  "journals": {
    "default": {
      "journal": "/mnt/HDD/Documents/journal/journal.txt",
      "encrypt": true
    }
  },
  "editor": "vim +Wrap +Goyo +EndOfLine",
  "encrypt": false,
  "default_hour": 9,
  "default_minute": 0,
  "timeformat": "%a, %d %b %Y %H:%M",
  "tagsymbols": "@",
  "highlight": true,
  "linewrap": 120
}

These are my personal settings and will most likely be different based on your setup. For example I have a common hard drive that I use in each OS so that's where I'm placing my journal, I also preferred a different date-time format.

One current downside is that it has to be a .txt file, personally I'd like to be able to have different formats like markdown.

For the "editor" setting we have the command to run with our chosen editor, in this case Vim, we'll go over the other arguments next.

Vim Configuration

How you choose to configure Vim can be a very personal thing.

Therefore what I recommend here is just that, my chosen ways to create a super minimalist and focused writing environment for journaling.

Our plugins and commands will ensure this line in jrnl_config works:

"editor": "vim +Wrap +Goyo +EndOfLine"

Wrap

When writing in vim, long lines will not wrap how you might expect them to, this command will enable 'normal' wrapping.

command! -nargs=* Wrap set wrap linebreak nolist

Use it with :Wrap.

Source: Vimcasts

Goyo

This one is actually 2 vim Plugins, Goyo and Limelight.

Goyo enables distraction free margins while Limelight offers 'hyperfocus-writing'.

These are vim plugins so make sure you have a plugin manager installed, if you don't know which you can use Vundle.

• Goyo
• Limelight

After enabling them in your `.vimrc`, we need to add a few changes to ensure they work perfectly. We want Goyo and Limelight to be enabled at the same time and, due to a quirk of Goyo, make sure that quitting vim completely quits.

.vimrc

" Goyo Config
" 120 is a subjective value that I like let g:goyo_width = 120

" Ensure :q to quit even when Goyo is active
function! s:goyo_enter()
    execute 'Limelight'
    let b:quitting = 0
    let b:quitting_bang = 0
    autocmd QuitPre let b:quitting = 1
    cabbrev q! let b:quitting_bang = 1 q!
endfunction

function! s:goyo_leave()
    execute 'Limelight!'
    " Quit Vim if this is the only remaining buffer
    if b:quitting && len(filter(range(1, bufnr('$')), 'buflisted(v:val)')) == 1
        if b:quitting_bang
            qa!
        else
            qa
        endif
    endif
endfunction

Source: Github

EndOfLine

This is simply a normal Vim command that I needed to be able to give it as a flag to the vim launching command. You'll see the use for this when we look at jrnl templates.

command EndOfLine normal! $

jrnl Extras

We now have jrnl and our editor configured for an excellent journaling experience but you might be looking to take it a bit further, here are 2 extra things you can do.

jrnl Templates

When journaling, even though you might want complete freedom, it sometimes helps to have some structure.

The way to do this with jrnl is by importing a file as an entry which we then use as our template. These could be questions or goals you always end up writing when journaling or things you want to make sure you think about like listing 3 things you were thankful for or what goals you want to focus on today.

Now while jrnl doesn't directly support templates, it makes a new entry with a template that you then need to reopen and edit. I've enabled this with a bash alias, one for the morning and one for the evening. This depends on how your template is set up.

.bashrc

alias jrnlm='jrnl < [path/to/template/file.txt] && jrnl -1 --edit'
alias jrnle='jrnl -on today --edit'

The `EndOfLine` argument when launching Vim will ensure our cursor is at the right place to then write our entry's title. If you don't use templates then it isn't necessary.

Journal Exporting

Journals are a rather static format, once written you're not meant to go back and change things, what would be nice is to then export our entries to a pdf. We'll write a bash function to do this it could then be called regularly with a cronjob and create a pdf library of your journal.

This particular function assumes you write your `.txt` files with markdown syntax and that you have `pandoc` installed to manage the markdown to pdf transformation.

.bashrc
function exportJrnl { jrnl --export markdown | pandoc --pdf-engine=xelatex -s -o "$1"; }

As an argument, the function takes the name and/or path to export the journal and will turn the whole journal into a pdf. You can change the jrnl flags to only get the entries of the past year or month.

Conclusion

I can't make you start journaling but I hope this at least gives you an incentive to try it out. If you were already interested but couldn't find a way to fit it into your existing workflow hopefully this method will inspire you.

Journaling is honestly fun and incredibly helpful, but for developers today I think that's not enough, we also need to be able to tinker and apply our own personal touches, with this setup there really are no limits to what you can do.

Cheers and happy journaling!