What is a developer journal?

Solve your future problems faster by logging the most useful things you've already learned.
185 readers like this
185 readers like this
Writing in a notebook

Pexels, via Pixabay. CC0.

One of the best parts of working in computer science is that our jobs center on solving problems. While many of us joke that continually struggling to figure things out is frustrating, we do it because there is nothing quite like that feeling of finding a solution. Then, of course, the momentary euphoria ends, and we move onto the next problem.

The hope is that our solution is another data point that propels us towards becoming a more accomplished and effective engineer. But what about all the times we encounter an old problem, one we've already solved, and cannot remember where we found that one, tiny piece of information that allowed us to fix it? Being an engineer can often feel a bit like you're living through Groundhog Day, always in a place where you know you've solved something sort of kind of like this before. My solution to this is a developer journal.

Benefits of developer journals

The idea behind a developer journal is that making relevant notes as you go about your tasks can help the future you. The technology industry requires us to continuously learn new technologies, deepen our understanding, and be able to handle quick, one-off uses of one tool or another—it's all part of this line of work. Having a journal helps you keep track of your learnings. Even if you work with a tool only briefly, being able to reference your journal the next time you use the tool can limit that loss of muscle memory and improve your recall. However, that's not its only benefit.

Einstein's advice to "never memorize something that you can look up" is a concept many engineers take to heart. Choosing not to memorize things may clear up some space in our brain to focus on the bigger-picture problem. However, when we look things up, we're using time and energy and taking ourselves out of the development flow. A developer journal allows us to strike a balance between memorizing everything and looking things up every time we encounter them. If the content you're looking for is written in your own terms, somewhere that's easily accessed, your life as an engineer just became easier.

The ultimate benefit of a developer journal is one of morale. We tend not to see our day-to-day progress; we only realize how much we've grown when we look back over periods of time. Having a physical manifestation of growth is a wonderful thing. Maybe you wrote something down a year ago that you no longer need to reference now. Maybe you've matured from simpler tasks to much more complex ones or mastered a technology you could barely understand before. A developer journal is an excellent history of all that you've done.

Types of developer journals

Developer journals are personal, but they usually encompass a mix of solutions, notes, helpful tricks, and quick links to resources. Because they are made to fit individual preferences, they can take many different forms.

For example, they can be offline (e.g., a physical, written journal) or online. Digital journal content can be formatted using Markup or some other tool, or plaintext if you prefer. Journals can be organized chronologically or by topic. Finally, journals can be public or private.

Use whatever solution makes your journal most accessible and usable for recording content and finding content when you need it. Luckily, there are many incredible open source tools that you can use to facilitate your developer journal, such as various Linux journaling applications, Evernote-style applications, and command line note-taking apps.

What to put in a journal

If you're not sure what to include in your developer journal, think about what types of resources you use somewhat regularly or as references. A journal might include a code snippet or a link to a particular line in a repository. It's common to put a simple link to a particularly useful blog post or tutorial. One of my most helpful entries is a brief writeup of the process I use to flash firmware onto a board.

Here is a quick example from my developer journal. Last year, I noticed that a process I often used would freeze on me. I kept forgetting the command for manually killing it in terminal, so I wrote it down. The following is a screenshot of my journal entry. It's plaintext, available offline, and unformatted. It's simple, and it works for me. My journal's chronology helps me a lot since I tend to remember when I last needed the answer, even if I don't remember the answer.

code snippet to kill a process

So, the next time you find yourself ecstatic that you've solved a problem, write down some quick notes. The next time you come across a resource that really helps, copy the link. And almost more importantly, make a note of the next piece of simple syntax you google. Having a self-curated document of the quick-lookup content that applies most often to your development process is invaluable. Looking back at it over time and recognizing how much you've learned is an added bonus.

picture of laurie
Laurie is a software developer, conference speaker and frequent blogger. During normal business hours she is a consultant at Ten Mile Square. Depending on the day she can be found using any number of technologies from different languages to frameworks and other support tools. When she isn't writing code you can find her playing board games and eating cupcakes.

9 Comments

No, don't log the things you have learned. Log everything you do. That includes hopeful ideas that don't work out, the false starts, the dead ends. The main purpose of an engineering journal is to prove you have done the work. Not only does this to support claims of patent, it improves your learning. You learn a lot more from your mistakes.

Nobody goes directly from point A to B. It is the bad ideas that prove a journal is real. Any journal that contains only the good stuff is useless.

That's definitely a valid way to do it. The point of a developer journal is to help you as an individual, whatever that means. That's why I point out all the different ways it can be structured. It can also include a variety of notes, mine certainly does!

In reply to by Shawn H Corey

I agree Shawn, but you should also log everything you do as well. From an engineering perspective if you date and log all entries these effectively become a legal record of what you are doing. In the event you are ever being sued over an intellectual property challenge your work log can be powerful ally in helping support your position. Good article and good commentary

In reply to by Shawn H Corey

I agree. When I got my first job out of college, I worked for a government contractor who required each engineer to keep a journal. An entry had to be made, detailing the day, each day every day. My supervisor had to review and sign it.

The company benefited from it and some of my coworkers were told to file patent applications based on their entries. Of course, by contract, any patents we applied for were owned by the company..

Once I got into the habit of writing a daily journal, I did it at every employer I worked for since.

In reply to by Shawn H Corey

Thanks for sharing, I constantly write everything work related in a bullet journal (old school paper) I can open a notebook and write an action item faster than someone opening a phone, table, laptop and capture the idea and later transcribe it where it needs to go. When I left a job a couple of years ago, I gave them my notebook as a transition document. I had written everything down as part of my job since I started. They had everything from day one :-)

Just to contribute a good web app: https://www.bookstackapp.com/ that a friend of mine has recommend me recently and I'm start to testing. Hopefully will be useful for someone.

Thanks for the motivation. I write mine on nano, mostly about what I do (change, break, build) on my Linux system. I came up with some classic formats to help me navigate the texts (# {date} ==> {explains what it is} ..)

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.