Rick Carlino

Lead software developer and a co-founding member at FarmBot

Co-founder and Maker of Things at Fox.Build Makerspace in St. Charles, IL.

[ 📨 Newsletter ] [ 💬 Contact ] [ 👤 About ]


A Year of Developer Journals with jrnl.sh

Keeping a daily journal is a great way to increase your effectiveness as a developer. My tool of choice for developer journaling is jrnl.sh.

Why Keep a Log

About a year ago, I started writing a daily (usually hourly) work log. Looking back on the year, I am pretty happy with the results.

My main reasons are:

Breaks and interruptions. Coming back to a task after stepping away bears a startup cost. Keeping a trail on recent actions for a given task reduces the burden of returning to work.

Bugs come back. Infrequent tasks are difficult to remember. “How did we do this last time?” is a common question on any development team.

Project management apps target teams rather than individuals. Trello is great for information dissemination, but things can turn TMI real fast if you use it as a public work log. It’s not always the right place for personal brain dumps.

Journaling makes debugging easier. Gathering observations, predictions and test results is a good way to pin down elusive bugs. For some bugs, it’s overkill, but for hard to isolate issues, it’s helpful.

Here’s a real example from my log book last month:


2017-09-21 11:38

PROBLEM:
    Messages do not arrive in message queue. No messages are visible in the
    message broker admin panel.

HYPOTHESIS:
    The recent update to our auth plugin is stopping messages from arriving,
    and probably not a network or client issue. Disabling the plugin *should*
    allow messages to pass through.

EXPERIMENT:
    Temporarily disabling the auth plugin on my development environment.
    Removing the auth plugin will allow messages to pass through

RESULTS:
    (Logs redacted for clarity)

CONCLUSION:
    The auth plugin (or its configuration) is probably contributing
    to the issue. Network issues are unlikely.

Why Jrnl and Not X?

Using jrnl

I tried other GUI and Web based journaling tools but found it to be a distraction from development work. Logging into a Web service, or having yet another desktop window open was a distraction. I found paper log books to be more usable, but they were easily left at home or lost.

As an offline app for the command line, Jrnl was the least obtrusive option and I was finally able to ditch my paper notebook.

Jrnl follows the “Unix Philosophy”. It has the right amount of features and operates on a text file, typically ~/jrnl.txt. I can easily pipe the contents through tools like less and grep. Backup is a trivial task. There are no signups or complicated file formats.

The most basic commands are:

  • Installation: pip install jrnl.
  • New entry: jrnl
  • Read 10 entries: jrnl -n 10

Using Jrnl as a daily software development log has increased my productivity immensely. I hope you give it a try as well. If you have any journaling tips of your own to share, please drop me a line on Lobste.rs or Reddit.