Matthew Lang

Keeping a journal is great for anyone looking to record their thoughts and experiences but I have also been keeping a programming journal for some months now and I have found it to be a great resource to help me through the day.

I got the idea for a programming journal from my late Granpa. During his retirement years he spent a lot of time learning to code. He kept a number of notebooks where he would scribble notes or code from what he did that day. Sometimes he would even write the code in the notebook in his armchair before taking to his PC the next day to try it out. Sadly these notebooks were thrown out before I could get a hold of them, but I still remember watching him scribble away in his big armchair.

For my journal I've opted to use a plain text file written in Markdown. Pen and paper would be okay for daily reviews, but copying snippets of code and urls is just much easier to do on your computer rather than transferring it to paper.

Choose a journal tool

First we need to choose a journal. Use a tool you're familiar with like Evernote, a plain text file or even pen and paper. Use whatever works best for you.

The reason I would encourage you to use a tool that you're already familiar with is that it will help you make a habit of this. If you want to try something new then feel free to but I think using a tool you're already familiar with makes it much easier to make this a daily habit.

What to journal?

There's several things that I like to keep in my programming journal. The first is the date. It acts as a reference and let's me review my past week or month in terms of work. I would say this is an essential element to your journal. Anything else that follows is optional but I find that a good mix of the following means I don't miss anything.

1. Snippets

There are snippet managers that let you save snippets of code for future use but the one thing I find lacking with these tools is the context in which why I would want to re-use code. Storing the snippet in a journal means that I can provide a background to how I discovered the snippet and any benefits or drawbacks there are to using it.

2. Articles

Bookmarking these in your favourite bookmarking application is good for a reference point, but what did you learn from reading the article. Is this information going to be easy to find in your bookmarks again when you need to find it? Maybe, but I find that storing the programming articles that I read in my journal means that it's easier to find them again.

3. Problems

Sometimes the best way to think through problems is to write about them. I've faced a number of difficult problems in code in my experience. Each time I've faced such a problem I write about it. I ask myself a few questions about the code and what needs to be done in order to maintain the code or write a new feature for it. Writing through such problems can often expose a chain of thought that might not have been immediately clear when you first faced the problem.

Such writing like this goes in the journal along with a summary indicating whether writing through the problem was successful or not.

4. Reviews

How many of you as programmers review your day? Did you record that big win you did today in refactoring that monster class into six separate service classes that are now fully tested and don't break the single responsibility principle?

If not why not?

I'm not the most confident of people so when I'm staring at some code that's holding me back, I find it useful to review my previous wins just to tell myself that yes I can overcome this problem. Sometimes just a review of what we did in the past is enough to get us in the right frame of mind to overcoming programming problems.

Do it daily

Perhaps the most important thing to remember about keeping a journal is to make sure that you fill it in daily. Don't worry about holidays or weekends where you're not working or programming. Missing days is fine.

I find that the easiest way to remember is that if I wrote any code that day, I record a journal entry on it. It doesn't need to be an epic monologue to describe the two line change you made to an open source project. Keep your journal entry relative in size to the amount of code you wrote that day.

In the past I would have articles bookmarked in one place, notes on code saved in a commit and snippets stored in a snippet manager. That's a lot of information spread out. Having it in one place makes it easy for me to review past experiences, search for snippets of code and find articles I have read. At the end of the week, I can pick out anything that requires a follow up.

It's working well for me as a learning and review aide and thanks to my Granpa for the idea!

I've been using Unread on my iPhone since it's launch and it is a joy to use. I star the articles I want to remember so that I have a list of them in my Feedbin account, then I share the article to my reading list. Simple right.

My only niggle is that I have to do these as two separate actions. Why can't they be combined?

Far be it from me to dictate the features of an application written in a language I have no knowledge of, but if these steps are coded into the app, then why do I have to do them individually? Surely there must be a way of allowing me to combine the actions I want to take when I star an article?

This isn't a dig at Unread or it's developer but what I'd like to see more of in applications is automation. One gesture or action to star an article and share it to the places I want to.

The argument against this would be that some people might just select every network and blog they're connected to and share it everywhere which is silly, so maybe limit the number of actions that can be combined to three maybe?

With a growing number of social networks, bookmarking sites and other blogs, it can take some people a number of gestures to share an article to the places that they want to. Why can't we combine these into one?

Being a fan of plain text files means that I am particularly picky about the services and tools that I sign up for. A service could have all the killer features that I need but if it can be made simpler by some scripting and text file, then I'll opt for that instead.

It all about data access. If I can access my data that your service stores and export it to something else, without too much fuss might I add, then I'm already going to like your service.

Todoist are an example of a good service in my eyes. I have their app on my iPhone and MacBook and I use it daily. It's a great service for managing your to do lists. The export facility though is a winner for me though. It does backups of all your to do lists on a regular basis for you. These backups can be downloaded (or exported if you want) to your computer. When you open them, the backup consists of a text file for each list with all your to dos listed in simple plain text.

At the other side, there are two types of services you need to watch for if access to plain text data is your key concern.

1. Services that don't allow access to your data.

These services are thankfully becoming less frequent now thanks to the fact that of those services that don't allow access to your data, there are some where you can at least access it through an API. Although this is only of benefit to developers, it does mean that with a little scripting you can grab your data and save it to a format that makes it easier for you to use.

The last time I checked, Path still doesn't allow access to your data in any kind of format and their API isn't published either which makes getting your data out and onto another network or journaling app much more of a manual process.

2. Services that allow access to your data but in a format other than plain text.

When I say a service uses something other than plain text, what I mean is that the format that they export to might be readable by any text editor but could be in a less friendly format like XML.

This is definitely down to personal choice and experience, but I am more comfortable working with JSON files than I am with a format like XML.

I use Evernote a lot now. Mostly for my freelancing work. When I exported some notes I created as part of my evaluation of it, I found that the notes were exported to a format of XML. Not user friendly at all if you don't have any experience with programming and you want to take these notes to another package.

Thankfully though Evernote does export to HTML which is far easier to read and while the HTML can't be imported back into Evernote should you need to, HTML is easier for reading your notes into another service.

This is the best of example I have of a service that exported to an unfriendly format. The reason why I still stuck with Evernote was that I can export the notes to HTML which is easier for me to script than XML.

Plain Text Please

If a service exported to anything more complicated than flat file with XML based markup then I wouldn't use that service. It's just a matter of having my data accessible in a format that doesn't inconvenience me.

Data access is a key criteria for me when assessing services that I want to use. My data should be accessible and ideally in a format that doesn't need a programmer to make sense of. Plain text formats win in this aspect due to their instant readability. Everything else is just a hindrance in my eyes.

via PEDAL Consumption

I need answers. Not right now, but definitely later on.

I've an idea in my head to turn my Grass Roots Productivity series into a book. This involves what many in the trade refer to as 'writing'. Therein lies my first problem.

Where do I begin?

For my only attempt at NaNoWriMo I just wrote a short introduction to a story. Each subsequent day I wrote more and more. No planning, no outline, no overall story to start from. Needless to say I struggled some days and faired better on others.

Is an outline really necessary though? I don't know. I've never written an actual book before. Some people say just write, others say outline first.

I suppose at the end of the day what I have as a first draft is not going to be the finished article and it will need to be read, edited and reviewed a number of times before I publish it. I'm not looking for a the winning recipe to writing a prize winning novel. I'm looking for practical advice to starting a book.

• Do I outline the book?
• Do I just write to see where it takes me?
• Do I build on my existing blog posts?

I've got too many questions and no answers. Bugger it, I'll draft an outline and start writing from there. I need to start somewhere.

It isn't often you find yourself using an app that is just effortless and simple to use. If you have an account with FeedBin, FeedWrangler or Feedly, then you'll want to check out Jared Sinclair's new app, Unread.

The complete list from NB.

I wrote about IAPs last month and now after seeing this, I will no longer support games developers who trade a fair business model for greed.

In the quest to find news users for people to follow in my Netterpress newsletter, I started putting together a few scripts that would poll new accounts created on App.net and update them over the course of the week. I only filtered for accounts categorized as 'human'. I figured that this would limit some of the spam accounts I would get. At the end of the week I would sort the accounts by the number of posts made for each account and then starting hand checking each account from the top of the list looking for interesting users to include in the Netterpress newsletter.

A sound idea in theory, but when it came to checking the accounts, I was disappointed to find that most of the active accounts at the top of my list were in fact spam accounts or valid accounts entirely powered by automated feed tools. There only a handful of actual human accounts in the fifty most active accounts that I looked at last night.

I've never previously done this on other social networks like Twitter or Facebook, but given my experience on Twitter in the past it's hard to be surprised by this.

Social media is it's own worst enemy in my eyes. The very tools that make it easy for us to post from one location to different networks are the very same tools that are used to automate the posting of irrelevant and unsolicited content.

The barrier to many social networks is nothing. All the networks I have heard of are free. Even App.net has a free tier for anyone to join. It's that free entry that makes it so appealing for many, but to others they see an opportunity to post irrelevant content.

In App.net's case, there is a growing number of feed accounts appearing on the platform. While that's okay for feeds that deliver valuable content, there's no getting away from the fact that people will setup accounts to deliver unwanted content, regardless of the social network you use. It doesn't matter what social network you are a member of, there will always be spam accounts trying to dilute the pool of valued content.

I'll be checking through the data over the weekend in preparation for the next Tuesday's newsletter. Hopefully I'll be able to pull together a list of some new users to recommend to others for the next edition of Netterpress.