How and Why I Journal

I used to hate writing. I never understood the point of our various writing assignments in school. I especially hated those times where we were expected to keep a journal. It never really felt like something I needed. But that all changed in my mid-twenties when I realized that as the technical lead for multiple products it was no longer possible to keep “everything in my head” and I started to change my tune. In retrospect I really should have discussed this stuff further with a co-worker I had earlier who kept a journal every day in a good ol’ composition book. After all I did take away the idea that it’s important to get out a first draft since once you have something you can then talk about it and figure out what it is that you actually wanted to write... though I’ve mostly applied this idea to software and not writing.

My early “journaling” was haphazard and mostly consisted of writing blog posts about various bits of technology I was working with. Often these were for the internal work blog (though from time to time I posted things on my own website) and dealt with non-publishable things since they contained company proprietary knowledge. At this point in time I bet many of those things have probably rotted to the point where it would be okay to release them on the world (like my crazy post about using Unreal Tournament and some custom tooling to convert our 3D language training game content into Flash animations).

I continued on with that mode for many years until I joined Mashery in 2013. Working for Mashery was a completely new experience for me. I was in a new city. I was working for a larger company. I was going to be working on new things since I’d never worked for a company which didn’t produce some sort of application for end users. So I approached the job as an opportunity to more seriously pursue this journaling thing. It was also the first job where I encountered a modern team chat[1] but that probably needs its own post[2].

[1] HipChat (RIP), Slack, Flowdock, Campfire and Mattermost are the others I’d consider as “modern” vs legacy team chat like IRC

[2] proposed title “Dances with Bots”

Since I’d been doing these things in a blog up to this point I decided to shove everything into my personal space in Confluence (not the best wiki ever... especially since they went all WYSIWYG all the time a bunch of years back). I started by creating a page for each week by hand with sections for each day and then would pile up my notes by editing the page throughout the day. This wasn’t ideal but it did the job and over time I started building little bits of automation to help manage the process (this was at Intel so since they used work week numbers for all sorts of things... I adopted the process... though I think in retrospect they weren’t using ISO-8601?weeks so there was a bunch of scripting to try and deal with the differences). So each Monday I’d start a new page for the week numbered like this: 2013.45.

These were a much more haphazard form of journaling and so some days might contain many details since I was working on a variety of things... or might contain no entries as I wrestled with some administrivia which I’d talked about before and didn’t want to rehash. I kept this up for many months and then “fell off the wagon” for a time, but during my last year and a half (part at Intel... part at Tibco) I was pretty dedicated to the journaling project and managed to write things in over 90% of weeks. When I was wrapping up my time there I actually dumped out all the journal and other blog writing I’d done and discovered I’d written over 500 pages of notes while there.

At my next role I decided to continue the practice... but it was just so damn hard. The new job was a SharePoint shop and I’d never had the “pleasure” of using SharePoint. I managed to keep it up for a couple of weeks... but doing anything sane in SharePoint was a challenge. And it didn’t help that it kept eating things which I wrote... or worse eating things I wrote previously while I was editing my post for the workweek. I quickly grew frustrated and started looking around for a new solution.

It was at this point that journaling and modern team chat started to intersect. This new job used FlowDock for their team chat. It had this new threading thing (hadn’t used Slack really at this point and HipChat had no such concept) and I realized I could probably use it as a journal directly. Chat actually is a good model for what I was doing anyway since they were often kind of small, needed to include small code snippets or images, and I wanted to share them... so I created a public channel[3] and started journaling into there assuming that I’d be able to leverage FlowDock’s API in the future to get the journal “out”. I also invited various members of my team to follow my journal and over time developed some conventions to get them to interact with it in a way which kept their commentary out of my flow (lots of threading... but keep in mind that flowdock threading is very different from that found in slack so there’s some subtlety here... there’s probably another post in that as well[4]).

[3] will return to this in the Dances with Bots post.

[4] These are the chats I’ve known (I’ve known? why is this triggering a memory of some song lyrics or something from summer camp... “There is too much to say and it goes in all directions” as Ted Nelson says)

I then put a little bit of energy into exporting the channel from FlowDock with some simple rules about indenting of other folks' comments. This actually turned out to be trivial in that environment since FlowDock stores all their posts as markdown (why Slack? why didn’t you just do this? Markdown had already been around for 5 years!). And since we were a GitHub Enterprise shop it was a simple matter to convert those into pages using the same YYYY.WW scheme I’d used back at Mashery. Took a little extra work to figure out how to extract attachments (in particular images) and code snippets and get them showing nicely, but for the most part FlowDock’s use of markdown had taken care of parts of the problem. But this took some doing when I tried to replicate it at my next job where we were using Slack and Confluence.

And that is pretty much it... a brief history of the development of my journaling process. I still use some variant of the process today wherever it is I happen to work at the moment.