[Ed. note: While we take some time to rest up over the holidays and prepare for next year, we are re-publishing our top ten posts for the year. Please enjoy our favorite work this year and we’ll see you in 2025.]
Writing is a fantastic tool for processing and communicating abstract ideas. And developers are steeped in abstract ideas! From system design to the finest implementation details, we keep a tremendous amount of information in our heads.
At the project level, a small army of project managers, product managers, engineering managers, and scrum masters (sometimes the same overworked person) helps us figure out what to build next. We turn to project management tools like Jira to track our progress. But at the code level, it’s easy to get lost.
Fortunately, there’s a way to keep your thoughts organized around the nitty-gritty: a developer’s journal. A dev journal is a tool to track what you’re doing and why. Although this might feel like a chore at first, keeping a journal will save you tons of time and prevent many headaches as you work. It might also get you promoted.
Why bother?
It’s a pet peeve of mine when self-help books spend chapters selling you on the idea before telling you what to do. So, here’s my tl;dr pitch for dev journals: you’ll write better code if you can focus 100% of your attention on solving one clearly-defined problem at a time, and you’ll grow as a developer by reflecting on what’s working and what you’re struggling with.
A developer’s journal is a place to define the problem you’re solving and record what you tried and what worked. That’s it. The rest of this article will offer techniques and strategies for getting there.
Here’s what your journal will help you do.
1. Define what you’re doing
While the product feature you’re working on might be well-defined, it’s your job to figure out the implementation, and it’s easy to get lost in ambiguity. Some programmers begin work by writing a to-do list right in their text editor. Use your dev journal to outline everything you need to complete your ticket or task. Define a specific action to tackle next. This’ll be helpful to reference if you get lost down the line.
2. Reduce ambiguity
It’s okay to feel uncertain about what you should do next or how to solve the problem you’re working on. Don’t work through the confusion by writing a bunch of code, which could take hours. Instead, take five minutes to get your uncertainties and the hypothesis you have out on paper. What exactly do you not know? How will you find out? What do you think is going to happen? As a wise man once said, “A problem well-stated is a problem half-solved.”
3. Learn from your experience
Once you’ve completed a chunk of work—a ticket, feature, or project—you can review it and learn from what was difficult and what you did well. You can also share your learnings with your teammates and manager. Rather than ambiguously “leveling up,” you can read exactly what you did and how you approached it.
4. Don’t get sidetracked
As you start to work on your well-defined engineering task, it’s natural to get sidetracked. This is exacerbated for developers with ADHD (wait, don’t read that article just yet). You might stumble on some crummy code and want to refactor it, find yourself working in a part of the codebase you didn't anticipate touching, or need to research some underlying technical concept. Before long, the afternoon slump hits and you're not sure what you did all day.
While you can sometimes make a tiny change or look things up as you go without interrupting your flow state, constant context-switching makes it tough to accomplish deep work. Get the thoughts or questions you’re having out of your head by writing them down in your journal, then address them at a later date.
5. Get your worries out of your head
You can use a dev journal to keep track of your emotions, too. Morning Pages are a popular technique for clearing the "clutter" in your head at the start of each day. You can try this approach with your dev journal. Are you nervous, anxious, excited? Get these feelings down on paper so you can clear your head and give the technical problems your undivided attention.
How to keep a developer’s journal
I’m glad you’re still with us. Now that you’re hopefully excited to keep a dev journal, here’s how you organize and use your new tool.
1. Set up your journal
Pick a place to write
Any popular text editor is fine. You can even use your code editor and simply create a new text or markdown file (just remember to .gitignore the file). What’s faster than changing tabs?
Don’t fall into the trap of setting up a system for hours only to abandon it once you start going, like buying the nicest journal only to realize you don’t want to write regularly. Do you have somewhere you can quickly type? Good. You’re ready!
Although you can also use a physical notebook, it’s probably not the best idea. You’ll lose the ability to link stuff and paste bits of code, which can be helpful. It might also break your flow to switch between your screen and a notebook.
Get in the right mindset
Your dev journal is your private document to organize and process your thoughts. The writing should be clear and readable to you, but it doesn’t need to be “good writing” by anyone else’s standards. Aim for “refrigerator to-do list” rather than “high school English essay.”
As long as the notes make sense to you, you should feel comfortable writing quickly. Don’t obsess over formatting, organization, or phrasing. You might find yourself chucking bits of code or links in your journal; there might be typos, different loosely-defined ideas. As long as you can still navigate it, that’s fine! These things are happening in your head anyway; get them on paper so you can think.
Customize as you go!
To start, consider breaking up your writing by day. Each day, write down your goal (maybe broken down into a to-do), and a short recap. We’ll discuss how to tackle these shortly.
Beyond that, there are no hard rules for organizing the journal. You might have sections for notes for 1:1s, things to look up later, clever names for your future woodworking business, and so on.
The main takeaway here is that your journal is customizable. Make sure to revisit whether it’s working for you as you go!
2. Before you start coding
At the start of each working session (this could be a day, ticket, or pomodoro session), define your goal for the session, even if it seems really obvious. What do you want to achieve today? Do you have a clear, well-defined coding task you need to accomplish? Do you need to explore something in the codebase? Are you prototyping? Do you need to test a hypothesis? How will you reduce the ambiguity?
Some days, this will feel straightforward. Other days, you’re going to feel confused, unsure, or itching to get started. If you feel discomfort at articulating your thinking, you’re probably not clear enough about your solution. Good! That’s the whole reason you’re keeping a dev journal.
As with rubber-ducking, it’s better to think through the ambiguity before you start coding, not while you’re in the thick of it. You can think of it as separation of concerns, or as putting on your architecture hat before you put on your engineering hat. When you’re writing code or making sense of code, you want to be able to focus 100% of your attention on the task in front of you.
3. While you code
Write when you get stuck
If you find yourself thinking through a problem for longer than a minute, jot your thinking down in your journal. If you’re stuck in a frustrating debugging session, write down everything you tried so far. This’ll make it easier to organize your thoughts and ask for help if you need it.
“How the heck do I split up this component? I tried, and there are all these side effects.”
“I’m hitting a weird TS error. I checked the imported interface. I tried using optional chaining. I tried using `any` on everything.”
Write when you figure things out
When you get unstuck, jot down the solution or logic that got you there. Remember: don’t judge yourself; just write how things are. This’ll be really helpful in uncovering what works for you in the long term.“
OH! I can move state up to a global store and just access it from all these different components; there was a super helpful article by React Person I Like.”
“Forgot the return again, ugh.”
“Turns out we have a whole module for this at app/src/etc and it was in the docs the whole time.”
Get ideas, questions, and todos out of your head
You’ll naturally generate ideas and questions as you work on code. Most of the time, it’s not worth interrupting your work to pursue these. Writing these tasks down will help unburden your brain so you can stay focused on the code. If the task is well-defined, you might even write a TODO right in the code. But most ideas aren’t that granular, so you should chuck them in your dev journal. You can batch these in dedicated Questions or Ideas sections to review later.
Of course, sometimes you’ll need to pursue a thought—check a different file, research a new concept, or look up some syntax—in order to complete your current task. But most of the time, you can look things up or even add a ticket to implement/prototype a new idea.
4. When you finish your task
At the end of the coding session, write down how it went without judgment. Remember, this is for your eyes only. Be candid.
Were you able to complete the task you set out? Was anything more challenging than you expected? Did you misjudge the difficulty or complexity of the task? Can you identify what frustrated or challenged you? Would you want to do anything differently when you get back to it tomorrow? Are you blocked on anything? Did you do anything you’re proud of? In short, do your own retrospective of your day.
Tips for success
Make journaling a habit
Get in the habit of writing at the beginning and end of every coding session. Keep the journal nearby; it should always be a tab away. You should be able to check your notes or make more notes at a glance.
You might be tempted to skip documenting the obvious some days, but I encourage you to stick with it. You’re not simply writing more; you’re becoming more mindful about your code.
Your dev journal becomes more and more valuable the longer you keep it as patterns begin to emerge.
Be direct
You don’t need to hit a word count. Say what you’re thinking in the words that come to mind, in the shortest way you can say it. Don’t worry about sounding smart or being neat. Nobody’s grading you. This isn’t standup; you don’t need to impress anybody (although, this is going to make standup much easier, since you can just check your notes).
Because writing down your reasoning forces you to confront the ambiguity sooner rather than later, articulating your thoughts might feel hard. But you’d have to deal with it anyway, and you don’t want to interrupt your precious coding focus to think about what problem you’re solving.
“I’m not sure what the best pathfinding algorithm is or how to compare them. Going to research the top ones to understand the tradeoffs.”
“The response JSON has a session attribute but I’m not clear about the difference between the express session, the server session object, and the concept of the session and the stuff we’re caching in the front-end data store.”
Reflect on your needs
As I said earlier, your dev journal should include whatever you need to be effective. For example, after experimenting with Morning Pages in my personal life, I found it useful to voice my anxieties and negative self-talk.
I would write things like, “Oh god, I can’t believe this is the third day I’m stuck on this problem” or “the client is paying me a bunch of money and I feel like an impostor,” and I’d feel better after getting it off my chest.
These are not glamorous thoughts, but if you’re having them anyway, get them down on paper so you can focus, rather than bottling and ruminating while you work.
Learn from your experience
Set aside a little time at the end of a sprint, month, or quarter to review your developer journal. You don’t need to read the fine details of what you did each day. Pay attention to where you struggled and what worked well for you, and what you accomplished each day.
These insights are very helpful for:
- Understanding how much work you’re capable of doing
- Your 1:1 meetings with your manager
- Your self-reflections for the performance review process
- Team retros
- To share with your coworkers and manager to help level up your team
- Writing future blog posts or long-form pieces
- Your brag doc for future career-advancement conversations
Consider writing your learnings from the reflection down in the same journal; you can title it “takeaways/learnings from this sprint/project/quarter.” Once again, this’ll push you to reflect on what you’re doing. The takeaways will make standups, retros, and one-on-ones much easier.
Consider sharing your learnings with your team and your manager. If you’re struggling with a concept/tool/part of a codebase, chances are your coworkers (especially newer team members) are too.
Stay mindful
Writing alongside your regular coding work might seem like a whole other job, but if you stick with it, it’ll become second nature and it’ll save you tons of time. It’s much better to be confused in one file at the start of the project than when you’ve written a bunch of code in multiple files in the middle of the project. Take five minutes to plan out your day now instead of running around in circles later.
A good developer’s journal should do three things:
- Nudge you to think through your ideas and plan each day before you start coding.
- Make you more mindful of your successes and struggles so you can level up.
- Clear your mind of everything that gets in the way of coding.
Try keeping a dev journal on your next project or sprint. You might be surprised by how much more effective you are!