Software development is hard. Organizations, small and large, can be very inefficient sometimes: people waste their energy on endless meetings, vague specification documents, pointless "reply-to-all" emails. Working as a freelancer in such environments is perhaps even worse, as you're supposed to be the hyper-efficient 10x developer unicorn that can make any problem magically disappear.

In this article we will see how, with a couple of simple tools, we can reduce noise, improve efficiency and guarantee better accountability.

Capture Information Today, Use It Tomorrow

When I started freelancing I wasn't prepared to handling people. I did somehow take for granted that, given the proper instructions, tools and timeframe, people would just do their thing and collaborate and smile and live well forever in peace and love.

That quickly proved to be utterly wrong.

People (including myself) are limited: we are all, to some degree, too busy, too lazy, too unreliable to handle everything. Also, there are certain types of workmates that tend to blame others for no real reason or, worse, to cover their own inefficiencies.

I needed to keep track of all those small pieces of information that do not fit in issue trackers or Trello Boards (referral). Some examples:

  • mr. Project Manager himself asks you to give priority to issue #555 instead of #666 "But please don't modify priority on issue tracker or the client will get mad"
  • your workmate gave you the IP address of the Test Server
  • you helped Jacob solving his bug on database code
  • you earned a discount voucher to be used within 24h
  • ...

As you can see, it would be overkill trying to fit everything in a tracking system. Yet, these informations are valuable both in the short as well as in the long term. One day your PM could show up in a meeting and accuse you of arbitrarily change issue priority; you could easily disprove that using your notes as a "proof" (albeit not so strong). Or you can quickly copy'n'paste codes, IP addresses, etc. from your notes, you just need to roughly remember when you stored them.

I soon discovered that I needed a "tool" with these features:

  1. lightweight and simple to use
  2. supporting basic text formatting: lists, bold/emphasis text, headings / hierarchies, links
  3. searchable

As my first attempt I tried using Mind Maps. I had this nice, ever-growing Mind Map full of notes, ideas and TODOs that grew and grew until... I wasn't able, or willing, to update it anymore. Call it a micro-management failure if you like.

Then, I discovered Markdown and it was love at first sight. It is very easy to learn, it has tremendous tool support, it works with plain text files. It looked perfect for my task!

Journal In Action

So, here is how I've implemented my own "work diary". I like to think that, since it didn't change much since I first used it, then it must be good!

The rules

1) One File Per Day

After a bit of experimenting I've found that the optimum, for my style of work, is to have one file per day. It keeps the files short (usually no more than one/two screens long) and you can concentrate on the notes of just that day.

2) Folders and file names

Separating folders by year and month has many benefits:

  • you can narrow your searches to specific periods
  • you can easily browse your archive

I like to keep my files in the correct order so I name them using the current date in a yyyy_MM_dd format. Here is a full, real-world example (notice the .md extension):

2014
  +- 01
  |   +- 2014_01_01.md
  |   +- 2014_01_02.md
  |   ...
  |   +- 2014_01_31.md
  \- 02
      +- 2014_02_01.md
      +- 2014_02_02.md
      ...
2015
  \- 01
      +- 2015_01_01.md
      +- 2015_01_02.md
      ...

3) Start with a date

On the first line of each file I insert the current date. While it seems useless at first, as you already have the file name, I think it's nice to have the date always displayed in the top row.

You can also use some special form like:

[journal - 02/01/2017]

This marks the file in a unique way and can be leveraged for very specific searches. You could also add some basic tagging, like:

[journal - 02/01/2017 dev, xyz project, deploy]

but don't go too far, or you'll lose simplicity.

4) Keep It Short and Simple

Whatever note you're going to put in your files, please keep it short and informative. You don't need to write in a good style, and you can safely put in your personal thoughts; try to think about it as your personal secret diary that no one has access to. Just be careful when you disclose information to others, as you may not want them to look at the entire log! (just imagine your workmates discovering things like "My XYZ workmate code is crap" or "I secretly stole the sandwich from the fridge")

Integrations

Editors

There are many programmer text editors out there with excellent Markdown support, either native or through some plugin: Atom, Sublime, IntelliJ IDEA or Visual Studio Code just to name a few.

I personally prefer Atom as it is cross-platform and lightweight, plus it has excellent support for my Markdown-powered diary.

  • Emmet-like macros, i.e.: t for TODOs, l for links, etc.
  • markdown preview with built-in GitHub style
  • fuzzy file search

Cloud & Backup

Having your files laid out in such a simple text-based system lets you leverage cloud backup tools like DropBox or GDrive. Just share the diary folder and you're done: instant synchronization on all your devices, backup, plus history & diff of past revisions!

Third Party Applications

In my daily journal I like to keep track of the tasks I'm working on, too. This works by simply pasting the link of the issue tracker / trello board / to-do item in my diary (see examples below). This leaves me with plenty of liberty, as you usually don't want to attach comments like "The database code sucks, had to rewrite the query" to the official issue tracker!

Some examples

Here are some real world examples, taken (and anonymized) directly from my own archive:

/2016/09/2016_02_09.md

# 09/02/2016

- [x] [Web Services Refactor](https://trello.com/c/45FvZJQ3)
  - Java version on server is WRONG!
  - had to call PITA-sysadmin
- [x] investigate Monster Cookie Problem
  - `utag.js`
    - row from 237 on
    - `utag_main` cookie is created and updated by XYZ, we cannot control it
- [x] privacy consent: persistent cookie
  - **PROBLEM**: version 1.3.x of Angular has sloppy cookie handling, better from 1.4.x on
  - POC using library
    https://github.com/ivpusic/angular-cookie
    instead of `angular-cookies`
- ngdocs:
  - grunt-ngdocs
  https://github.com/m7r/grunt-ngdocs
  - Starting off with NgDocs
  http://www.podpea.co.uk/blog/starting-off-with-ngdocs/
  - Writing AngularJS Documentation
  https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation

Preview

The above file renders nicely in the Markdown Preview pane of Atom Editor:

Markdown Journal Example Preview 1

/2016/09/2016_09_01.md

# 01/09/2016

# Activity

- [ ] Holacracy session 5/6 Sept: 1/2 days off?
- xyz-projects-api
  - [x] REGRESSION: Update Item configurations is broken
  - [PAUSED] (Bob) Slack 27/08/2016 - see below
  - [x] REVERTED!!!! Billing Info refactoring:
    - remove BillingInfo class
    - field `billingInfo` of type `Address`
- xyz-siteusers-api
  - [WAITING] (Jane) Check camel-case vs snake-case on user model
  - [ ] Add `xyz-siteusers-api.postman_collection.json`

## (Bob) Slack 27/08/2016

> - when you do add item, it's not possible to change leadTime
> - accessories data are missing
> - quantity is wrong
> [...]
> (admin) from siteusers user I should get a user profile

- [x] Check: change leadtime
- [ ] Check: accessories data
- [x] Check: quantity
- [x] admin: get user

Preview

Here is a preview of this journal entry:

Markdown Journal Example Preview 2

Further Work

How to have less meetings is a great and inspiring article by Josh Johnston of X-Team that brings further the concept of "work journal" to... an entire team on Slack!

Links