[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 unbelievable device for processing and speaking summary concepts. And builders are steeped in summary concepts! From system design to the best implementation particulars, we maintain an amazing quantity of data in our heads.
On the challenge degree, a small military of challenge managers, product managers, engineering managers, and scrum masters (generally the identical overworked particular person) helps us work out what to construct subsequent. We flip to challenge administration instruments like Jira to trace our progress. However on the code degree, it’s simple to get misplaced.
Thankfully, there’s a option to maintain your ideas organized across the nitty-gritty: a developer’s journal. A dev journal is a device to trace what you’re doing and why. Though this would possibly really feel like a chore at first, maintaining a journal will prevent tons of time and stop many complications as you’re employed. It may additionally get you promoted.
It’s a pet peeve of mine when self-help books spend chapters promoting you on the thought earlier than telling you what to do. So, right here’s my tl;dr pitch for dev journals: you’ll write higher code for those who can focus 100% of your consideration on fixing one clearly-defined downside at a time, and also you’ll develop as a developer by reflecting on what’s working and what you’re scuffling with.
A developer’s journal is a spot to outline the issue you’re fixing and file what you tried and what labored. That’s it. The remainder of this text will supply strategies and methods for getting there.
Right here’s what your journal will assist you do.
Whereas the product function you’re engaged on is likely to be well-defined, it’s your job to determine the implementation, and it’s simple to get misplaced in ambiguity. Some programmers start work by writing a to-do listing proper of their textual content editor. Use your dev journal to stipulate all the things you must full your ticket or activity. Outline a particular motion to sort out subsequent. This’ll be useful to reference for those who get misplaced down the road.
It’s okay to really feel unsure about what you must do subsequent or tips on how to resolve the issue you’re engaged on. Don’t work by the confusion by writing a bunch of code, which may take hours. As a substitute, take 5 minutes to get your uncertainties and the speculation you’ve out on paper. What precisely do you not know? How will you discover out? What do you assume goes to occur? As a wise man as soon as stated, “An issue well-stated is an issue half-solved.”
When you’ve accomplished a piece of labor—a ticket, function, or challenge—you may overview it and be taught from what was tough and what you probably did nicely. You too can share your learnings together with your teammates and supervisor. Reasonably than ambiguously “leveling up,” you may 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 locate some crummy code and wish to refactor it, end up working in part of the codebase you did not anticipate touching, or have to analysis some underlying technical idea. Earlier than lengthy, the afternoon hunch 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 stream state, fixed context-switching makes it robust 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 need to use a dev journal to maintain monitor of your feelings, too. Morning Pages are a well-liked method for clearing the “muddle” in your head at first of every day. You may do this method together with your dev journal. Are you nervous, anxious, excited? Get these emotions down on paper so you may 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 manage and use your new device.
Choose a spot to write down
Any fashionable 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 entice of establishing a system for hours solely to desert it when you begin going, like shopping for the nicest journal solely to comprehend you don’t wish to write commonly. Do you’ve someplace you may rapidly sort? Good. You’re prepared!
Though you can even use a bodily pocket book, it’s most likely not the most effective thought. You’ll lose the flexibility to hyperlink stuff and paste bits of code, which will be useful. It may additionally break your stream to modify between your display screen and a pocket book.
Get in the best mindset
Your dev journal is your non-public doc to arrange and course of your ideas. The writing needs to be clear and readable to you, nevertheless it doesn’t must be “good writing” by anybody else’s requirements. Intention for “fridge to-do listing” relatively than “highschool English essay.”
So long as the notes make sense to you, you must really feel snug writing rapidly. Don’t obsess over formatting, group, or phrasing. You would possibly end up chucking bits of code or hyperlinks in your journal; there is likely to be typos, totally different loosely-defined concepts. So long as you may nonetheless navigate it, that’s nice! These items are occurring in your head anyway; get them on paper so you may assume.
Customise as you go!
To start out, think about breaking apart your writing by day. Every day, write down your objective (perhaps damaged down right into a to-do), and a brief recap. We’ll focus on tips on how to sort out these shortly.
Past that, there are not any arduous guidelines for organizing the journal. You might need sections for notes for 1:1s, issues to search for later, intelligent names on your future woodworking enterprise, and so forth.
The principle takeaway right here is that your journal is customizable. Make sure that to revisit whether or not it’s working for you as you go!
At first of every working session (this may very well be a day, ticket, or pomodoro session), outline your objective for the session, even when it appears actually apparent. What do you wish to obtain right this moment? Do you’ve a transparent, well-defined coding activity you must accomplish? Do you must discover one thing within the codebase? Are you prototyping? Do you must 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, uncertain, or itching to get began. In case you really feel discomfort at articulating your pondering, you’re most likely not clear sufficient about your answer. Good! That’s the entire cause you’re maintaining a dev journal.
As with rubber-ducking, it’s higher to assume by the paradox earlier than you begin coding, not when 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 place 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 once you get caught
If you end up pondering by an issue for longer than a minute, jot your pondering down in your journal. In case you’re caught in a irritating debugging session, write down all the things you tried thus far. This’ll make it simpler to arrange 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 unwanted effects.”
“I’m hitting a bizarre TS error. I checked the imported interface. I attempted utilizing optionally available chaining. I attempted utilizing `any` on all the things.”
Write once you determine issues out
Once you get unstuck, jot down the answer or logic that acquired you there. Bear in mind: don’t choose 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 worldwide 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 now we have a complete module for this at app/src/and so on 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 value interrupting your work to pursue these. Writing these duties down will assist unburden your mind so you may 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 you must chuck them in your dev journal. You may batch these in devoted Questions or Concepts sections to overview later.
In fact, generally you’ll have to pursue a thought—examine a unique file, analysis a brand new idea, or search for some syntax—so as to full your present activity. However more often than not, you may look issues up and even add a ticket to implement/prototype a brand new thought.
On the finish of the coding session, write down the way it went with out judgment. Bear in mind, that is on your eyes solely. Be candid.
Had been you in a position to 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 pissed off or challenged you? Would you wish to do something otherwise once you get again to it tomorrow? Are you blocked on something? Did you do something you’re happy with? In brief, do your personal retrospective of your day.
Make journaling a behavior
Get within the behavior of writing in the beginning and finish of each coding session. Hold the journal close by; it ought to at all times be a tab away. You must have the ability to examine your notes or make extra notes at a look.
You is likely to be tempted to skip documenting the plain some days, however I encourage you to keep it up. You’re not merely writing extra; you’re changing into extra aware about your code.
Your dev journal turns into increasingly invaluable the longer you retain it as patterns start to emerge.
Be direct
You don’t have to hit a phrase depend. Say what you’re pondering within the phrases that come to thoughts, within the shortest means you may say it. Don’t fear about sounding sensible or being neat. No person’s grading you. This isn’t standup; you don’t have to impress anyone (though, this is going to make standup a lot simpler, since you may simply examine 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 arduous. However you’d need to take care of it anyway, and also you don’t wish to interrupt your valuable coding focus to consider what downside you’re fixing.
“I’m undecided what the most effective pathfinding algorithm is or tips on how to evaluate them. Going to analysis the highest ones to know the tradeoffs.”
“The response JSON has a session attribute however I’m not clear concerning 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 knowledge retailer.”
Replicate in your wants
As I stated earlier, your dev journal ought to embrace no matter you must 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 imagine that is the third day I’m caught on this downside” or “the consumer 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 usually are not glamorous ideas, however for those who’re having them anyway, get them down on paper so you may focus, relatively than bottling and ruminating when you work.
Put aside just a little time on the finish of a dash, month, or quarter to overview your developer journal. You don’t have to learn the nice 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 overview course of
- Group retros
- To share together with your coworkers and supervisor to assist degree up your staff
- Writing future weblog posts or long-form items
- Your brag doc for future career-advancement conversations
Contemplate writing your learnings from the reflection down in the identical journal; you may title it “takeaways/learnings from this dash/challenge/quarter.” As soon as once more, this’ll push you to mirror on what you’re doing. The takeaways will make standups, retros, and one-on-ones a lot simpler.
Contemplate sharing your learnings together with your staff and your supervisor. In case you’re scuffling with an idea/device/a part of a codebase, chances are high your coworkers (particularly newer staff members) are too.
Writing alongside your common coding work would possibly seem to be a complete different job, however for those who keep it up, it’ll turn out to be second nature and it’ll prevent tons of time. It’s a lot better to be confused in a single file at first of the challenge than once you’ve written a bunch of code in a number of recordsdata in the course of the challenge. Take 5 minutes to plan out your day now as an alternative of operating round in circles later.
An excellent developer’s journal ought to do three issues:
- Nudge you to assume by your concepts and plan every day earlier than you begin coding.
- Make you extra aware of your successes and struggles so you may degree up.
- Clear your thoughts of all the things that will get in the best way of coding.
Strive maintaining a dev journal in your subsequent challenge or dash. You is likely to be stunned by how rather more efficient you might be!
