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.
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.
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.
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 as soon as mentioned, “An issue well-stated is an issue half-solved.”
When you’ve accomplished a piece of labor—a ticket, function, or undertaking—you’ll be able to assessment it and be taught from what was troublesome and what you probably did nicely. You can even share your learnings together with your teammates and supervisor. Slightly than ambiguously “leveling up,” you’ll be able to learn precisely what you probably did and the way you approached it.
As you begin to work in your well-defined engineering activity, it’s pure to get sidetracked. That is exacerbated for builders with ADHD (wait, don’t learn that article simply but). You would possibly discover some crummy code and need to refactor it, end up working in part of the codebase you did not anticipate touching, or must analysis some underlying technical idea. Earlier than lengthy, the afternoon droop hits and also you’re undecided what you probably did all day.
When you can generally make a tiny change or look issues up as you go with out interrupting your movement state, fixed context-switching makes it powerful to perform deep work. Get the ideas or questions you’re having out of your head by writing them down in your journal, then deal with them at a later date.
You should use a dev journal to maintain monitor of your feelings, too. Morning Pages are a preferred method for clearing the “litter” in your head firstly of every day. You may do this strategy together with your dev journal. Are you nervous, anxious, excited? Get these emotions down on paper so you’ll be able to clear your head and provides the technical issues your undivided consideration.
I’m glad you’re nonetheless with us. Now that you simply’re hopefully excited to maintain a dev journal, right here’s the way you set up and use your new device.
Choose a spot to put in writing
Any common textual content editor is ok. You may even use your code editor and easily create a brand new textual content or markdown file (simply keep in mind to .gitignore the file). What’s sooner than altering tabs?
Don’t fall into the lure of organising a system for hours solely to desert it when you begin going, like shopping for the nicest journal solely to comprehend you don’t need to write recurrently. Do you have got someplace you’ll be able to shortly kind? Good. You’re prepared!
Though you can too use a bodily pocket book, it’s most likely not the most effective concept. You’ll lose the flexibility to hyperlink stuff and paste bits of code, which might be useful. It may also break your movement to change between your display screen and a pocket book.
Get in the precise mindset
Your dev journal is your personal doc to prepare and course of your ideas. The writing must be clear and readable to you, but it surely doesn’t have to be “good writing” by anybody else’s requirements. Intention for “fridge to-do checklist” relatively than “highschool English essay.”
So long as the notes make sense to you, it is best to really feel comfy writing shortly. Don’t obsess over formatting, group, or phrasing. You would possibly end up chucking bits of code or hyperlinks in your journal; there is perhaps typos, totally different loosely-defined concepts. So long as you’ll be able to nonetheless navigate it, that’s fantastic! This stuff are occurring in your head anyway; get them on paper so you’ll be able to assume.
Customise as you go!
To start out, think about breaking apart your writing by day. Every day, write down your purpose (possibly damaged down right into a to-do), and a brief recap. We’ll talk about the way to sort out these shortly.
Past that, there aren’t any onerous guidelines for organizing the journal. You may need sections for notes for 1:1s, issues to search for later, intelligent names in your future woodworking enterprise, and so forth.
The principle takeaway right here is that your journal is customizable. Be certain that to revisit whether or not it’s working for you as you go!
At the beginning of every working session (this might be a day, ticket, or pomodoro session), outline your purpose for the session, even when it appears actually apparent. What do you need to obtain at the moment? Do you have got a transparent, well-defined coding activity you want to accomplish? Do you want to discover one thing within the codebase? Are you prototyping? Do you want to check a speculation? How will you cut back the paradox?
Some days, this can really feel easy. Different days, you’re going to really feel confused, not sure, or itching to get began. For those who really feel discomfort at articulating your pondering, you’re most likely not clear sufficient about your resolution. Good! That’s the entire motive you’re retaining a dev journal.
As with rubber-ducking, it’s higher to assume by means of the paradox earlier than you begin coding, not whilst you’re within the thick of it. You may consider it as separation of considerations, or as placing in your structure hat earlier than you set in your engineering hat. Once you’re writing code or making sense of code, you need to have the ability to focus 100% of your consideration on the duty in entrance of you.
Write if you get caught
If you end up pondering by means of an issue for longer than a minute, jot your pondering down in your journal. For those who’re caught in a irritating debugging session, write down every little thing you tried up to now. This’ll make it simpler to prepare your ideas and ask for assist for those who want it.
“How on earth do I cut up up this element? I attempted, and there are all these uncomfortable side effects.”
“I’m hitting a bizarre TS error. I checked the imported interface. I attempted utilizing non-obligatory chaining. I attempted utilizing `any` on every little thing.”
Write if you determine issues out
Once you get unstuck, jot down the answer or logic that acquired you there. Keep in mind: don’t decide your self; simply write how issues are. This’ll be actually useful in uncovering what works for you in the long run.“
OH! I can transfer state as much as a world retailer and simply entry it from all these totally different parts; there was an excellent useful article by React Particular person I Like.”
“Forgot the return once more, ugh.”
“Seems we’ve an entire module for this at app/src/and many others and it was within the docs the entire time.”
Get concepts, questions, and todos out of your head
You’ll naturally generate concepts and questions as you’re employed on code. More often than not, it’s not price interrupting your work to pursue these. Writing these duties down will assist unburden your mind so you’ll be able to keep centered on the code. If the duty is well-defined, you would possibly even write a TODO right in the code. However most concepts aren’t that granular, so it is best to chuck them in your dev journal. You may batch these in devoted Questions or Concepts sections to assessment later.
In fact, generally you’ll must pursue a thought—verify a unique file, analysis a brand new idea, or search for some syntax—in an effort to full your present activity. However more often than not, you’ll be able to look issues up and even add a ticket to implement/prototype a brand new concept.
On the finish of the coding session, write down the way it went with out judgment. Keep in mind, that is in your eyes solely. Be candid.
Had been you capable of full the duty you set out? Was something more difficult than you anticipated? Did you misjudge the issue or complexity of the duty? Are you able to establish what annoyed or challenged you? Would you need to do something in a different way if you get again to it tomorrow? Are you blocked on something? Did you do something you’re pleased with? In brief, do your personal retrospective of your day.
Make journaling a behavior
Get within the behavior of writing at first and finish of each coding session. Maintain the journal close by; it ought to all the time be a tab away. You must be capable of verify your notes or make extra notes at a look.
You is perhaps tempted to skip documenting the apparent some days, however I encourage you to keep it up. You’re not merely writing extra; you’re turning into extra aware about your code.
Your dev journal turns into increasingly useful the longer you retain it as patterns start to emerge.
Be direct
You don’t must hit a phrase depend. Say what you’re pondering within the phrases that come to thoughts, within the shortest means you’ll be able to say it. Don’t fear about sounding sensible or being neat. No one’s grading you. This isn’t standup; you don’t must impress anyone (though, this is going to make standup a lot simpler, since you’ll be able to simply verify your notes).
As a result of writing down your reasoning forces you to confront the paradox sooner relatively than later, articulating your ideas would possibly really feel onerous. However you’d should cope with it anyway, and also you don’t need to interrupt your treasured coding focus to consider what downside you’re fixing.
“I’m undecided what the most effective pathfinding algorithm is or the way to examine them. Going to analysis the highest ones to grasp the tradeoffs.”
“The response JSON has a session attribute however I’m not clear in regards to the distinction between the categorical session, the server session object, and the idea of the session and the stuff we’re caching within the front-end information retailer.”
Mirror in your wants
As I mentioned earlier, your dev journal ought to embrace no matter you want to be efficient. For instance, after experimenting with Morning Pages in my private life, I discovered it helpful to voice my anxieties and unfavorable self-talk.
I’d write issues like, “Oh god, I can’t consider that is the third day I’m caught on this downside” or “the shopper is paying me a bunch of cash and I really feel like an impostor,” and I’d really feel higher after getting it off my chest.
These are usually not glamorous ideas, however for those who’re having them anyway, get them down on paper so you’ll be able to focus, relatively than bottling and ruminating whilst you work.
Put aside just a little time on the finish of a dash, month, or quarter to assessment your developer journal. You don’t must learn the fantastic particulars of what you probably did every day. Take note of the place you struggled and what labored nicely for you, and what you achieved every day.
These insights are very useful for:
- Understanding how a lot work you’re able to doing
- Your 1:1 conferences together with your supervisor
- Your self-reflections for the efficiency assessment course of
- Staff retros
- To share together with your coworkers and supervisor to assist stage up your workforce
- Writing future weblog posts or long-form items
- Your brag doc for future career-advancement conversations
Think about writing your learnings from the reflection down in the identical journal; you’ll be able to title it “takeaways/learnings from this dash/undertaking/quarter.” As soon as once more, this’ll push you to replicate on what you’re doing. The takeaways will make standups, retros, and one-on-ones a lot simpler.
Think about sharing your learnings together with your workforce and your supervisor. For those who’re battling an idea/device/a part of a codebase, chances are high your coworkers (particularly newer workforce members) are too.
Writing alongside your common coding work would possibly seem to be an entire different job, however for those who keep it up, it’ll change into second nature and it’ll prevent tons of time. It’s a lot better to be confused in a single file firstly of the undertaking than if you’ve written a bunch of code in a number of recordsdata in the midst of the undertaking. Take 5 minutes to plan out your day now as an alternative of working round in circles later.
An excellent developer’s journal ought to do three issues:
- Nudge you to assume by means of your concepts and plan every day earlier than you begin coding.
- Make you extra aware of your successes and struggles so you’ll be able to stage up.
- Clear your thoughts of every little thing that will get in the way in which of coding.
Strive retaining a dev journal in your subsequent undertaking or dash. You is perhaps stunned by how far more efficient you’re!
