[HN Gopher] The power of keeping a coding journal (2014)
___________________________________________________________________
The power of keeping a coding journal (2014)
Author : jstrieb
Score : 134 points
Date : 2023-06-12 14:13 UTC (8 hours ago)
(HTM) web link (thomasburette.com)
(TXT) w3m dump (thomasburette.com)
| semireg wrote:
| After years of solving the same electron code signing issues over
| and over I finally started keeping notes and now instead of
| wasting 6 hours troubleshooting I'm down to like 30 minutes. I
| guess that's progress. Agh!
| aatd86 wrote:
| I use github issues for that. I also have notes on my phone.
|
| Or when I design an algorithm,I use pen and paper and keep it as
| a trace.
| cratermoon wrote:
| The link to jrnl provided in the article is broken. It seems to
| now be at <https://jrnl.sh>
| gnuvince wrote:
| Recently, I've started using phpbb (with a docker-compose setup
| from Bitnami) for keeping personal notes. I find that it works
| better than pretty much everything I've used before. I like that
| when I reply to a thread to add an update, that post raises to
| the top, so it's harder to lose items.
| photoGrant wrote:
| This is borderline genius! Thank you!
|
| Stolen, doing!
| tommica wrote:
| What an interesting idea - my goto has been personal wikis, but
| personal discussion board seems like a great choice!
| philsnow wrote:
| If you're into emacs, org-capture is _great_ for this kind of
| thing.
| smegsicle wrote:
| what does your capture template look like, and where do you
| capture them to?
| Zambyte wrote:
| I'm not the same person but I use org-roam-dailies-capture-
| today with the default capture template for stuff like this.
| I do want to play around with making more useful capture
| templates.
| philsnow wrote:
| Some of my captures go into ~/org/refile.org, which I use as
| triage/inbox, but I usually use this template that puts
| entries into a datetree in another org file:
| (setq org-capture-templates (quote ( [...]
| ("j" "Journal" entry (file+olp+datetree "~/org/work/work.org"
| "Diary") "* %?\n\n\n" :clock-in t :clock-resume t
| :empty-lines-after 1) [...])))
| ArcMex wrote:
| I maintain physical and digital notes on my coding. Since I
| review them frequently, I find them helpful. The notes help me
| track progress or try out new ideas. Sometimes the very acting of
| writing reinforces my understanding of new and even old concepts.
| I would recommend most developers keep a journal of some sort and
| review it regularly.
| justinlloyd wrote:
| I keep a lot of lab notes. When I cannot think of what I need to
| do to move forward, I write out some lab notes of what I have
| done and ideas for what needs to be done.
|
| They usually aren't complex, and and often just a single line
| about something.
|
| I keep lab notes for whatever personal project I am currently
| engaged with, lab notes for the household (repairs, updates,
| documented procedures on how to start the furnace, etc), lab
| notes for work, lab notes for the RV, lab notes for the workshop,
| lab notes for the home network.
|
| Keeping informal notes on what has been done, what needs to be
| done, and thoughts about the doings has helped me immensely. An
| example of some of my project notes
| https://github.com/JustinLloyd/retro-chores
|
| I've got lab notes going back to at least the 1970's,
| https://justinlloyd.li/blog/word-search-game/ (1978) and
| https://justinlloyd.li/blog/word-search-game-part-two/ and
| https://justinlloyd.li/blog/better-date-format/ (1979) are some
| samples, though I didn't call them lab notes back then.
| matsemann wrote:
| I wish I was better at recording what I've done at work, uni,
| private. Just for my own sake.
|
| Some screenshots, notes etc of projects I've been part of. Cool
| to look back and reminisce about what I've done over about 20
| years of programming. Most of the early stuff is lost or
| forgotten.
|
| But the few things I can find from the early days I'm quite happy
| to rediscover. Even if it's just a page full of construction gifs
| and marquee tags I made as a teenager.
| greyman wrote:
| Might I ask those who does this - do you use one "global" journal
| for everything development related, or it is per-project?
| uLogMicheal wrote:
| I 100% concur, I comb through my log/journal every week looking
| for ideas/issues I have not properly documented. Really helpful
| for recall and organization.
| simonw wrote:
| I've been using GitHub Issues as a coding journal for a few years
| now and found it to work incredibly well.
|
| I work on most of my projects in public repositories and often
| end up posting hundreds of issues with thousands of accumulated
| comments across them all.
|
| I also have private repos which I use just for issue threads for
| coding journal mode entries that I'm not ready to share.
|
| Occasionally I'll take one of those private issues and make it
| public later on, for example this one:
| https://github.com/simonw/public-notes/issues/1
| jjice wrote:
| Very cool. Your notes seem very high quality and the fact that
| they'll be indexed by search engines is great for other people.
| velcrovan wrote:
| This is one of the reasons I like Fossil for source control. It
| has a wiki and a ticketing system built into each repo. Any
| branch or commit can have its own wiki page. You can customize
| the ticketing system and use it as a roadmap. All of that lives
| right within the same system as the source code. It's great.
| bachmeier wrote:
| I've never said "I wish I hadn't put all those notes inside
| this repo." Fossil is good, but you could probably do the same
| with Github or Gitlab, assuming you're willing to use the
| website.
| jasonpeacock wrote:
| TBH, once the feature/task/project is done...you're working on
| something else and all those thoughts and TODOs quickly become
| stale.
|
| CTRL-A + DEL is your friend, post-work.
|
| The biggest value of keeping notes _during_ a project is to
| prevent you from getting sidetracked by distractions. Write down
| the thought so it 's out of your head, then get back to the task
| at hand.
|
| DO NOT put them in your project backlog. That's how you get a
| 800+ list of items that get ignored and only add a huge mental
| weight to your backlog management. If you're going to ignore them
| for 3yrs and then finally delete them, why not start by deleting
| (not writing) them now?
| Aperocky wrote:
| Shameless plug on the same subject if you are vim user fond of
| terminal:
|
| https://github.com/Aperocky/diarycli
|
| `pip install diarycli`
|
| Alternatively there is a shell version if you are averse to
| python/pip package manager as well:
|
| https://github.com/Aperocky/diaryman/blob/master/diaryman.sh
|
| The only way I can get myself to write things down is to have it
| one commands away in the terminal.
| sureglymop wrote:
| How do you separate your work and personal journal? I journal
| every day in my free time but I can't sync that with my work
| stuff. I find myself wanting to go look at my personal notes but
| also write more as I'm working. The only thing that could work
| would be a cms where I could add things online.
| impyamin wrote:
| "The coding journal doesn't prevent me writing from writing bugs.
| " meta
| devrob wrote:
| Built one of these as a ruby gem in case it's useful for others.
| I use as a dev log and mini issue tracker for projects where a
| project mgmt tool feels like overkill. It can sync to your local
| knowledge base (for me obsidian) if you want too.
| https://github.com/aquaflamingo/devlogs
| pksebben wrote:
| I've been doing this for years, and I've developed a few "inline"
| methods to allow the journal to flow through multiple projects
| and maintain cohesion in the face of my otherwise-crippling
| tendency to do a million things at once and think too far ahead
| in the future. Perhaps some will be useful to others.
|
| Note that these all rely on vim bindings, as I use emacs-evil.
| The concepts are probably not too hard to implement elsewhere,
| though.
|
| - There is one 'main' journal, in my home directory, and a
| `devlog.md` journal in the root of every project I'm working on.
| These journals are linked by a series of paths so it becomes easy
| to `g-f` (goto-file) to jump to the devlog in question.
|
| - The footer of these journals consists of an immediate TODO, and
| the links to sub-journals previously mentioned.
|
| - at the end of each journal is a string (,./). This allows me to
| jump to the place where I'd just start writing (in vim/evil
| emacs) with a simple `/,./`. This bookmark always sits between
| the 'journal' component (the top half, where the mind-dumping
| occurs) and the directory of child projects / TODO at the footer.
|
| - All of these are committed to version control with a nightly
| cron job.
| dukeofdoom wrote:
| a ringed sketchbook works great for a journal like this, no lines
| on pages so you can draw diagrams. Dollorama in Canada has a
| great one for $4 or is it $5 now.
| bbor wrote:
| I'd personally vouch for dotted paper - best of both worlds!
| And colors help a lot. All of that is well supported on the
| iPad Pro; Apple in California has great ones for $900 now ;)
| HybridCurve wrote:
| Anytime I am laying out a UI or database it goes in a journal,
| diagrams for things as well. Any reference publications or online
| sources of information will be listed as well.
|
| If your development project is doing something novel, it is
| almost a necessity to keep records. It's really more of a
| research project at that point which becomes much more difficult
| to manage without diligently keeping notes of the process.
| dbrueck wrote:
| A dev log or journal can be very helpful, here are 2 ways in
| particular that really help me:
|
| - context switching - if you have a backburner or side project,
| it's easy to get pulled away from it for days or weeks (or more)
| at a time, and when you do make time for it, it could be just a
| few minutes here or there. The very last thing I do during each
| dev session is list the 2-3 things I hope to tackle in the next
| session. When I eventually make it back to the project, I can
| just jump right in on one of those items and not waste any time
| trying to get my bearings again. I slightly disagree with the
| author that the journal isn't a good place to track your todos -
| it's a great place if you are a solo dev and/or if the work is in
| its early stages - you want to capture quickly important ideas of
| things you might do later, and sometimes just writing them down
| helps you not work on them right now.
|
| - "impossible" bugs, or ones that are difficult to reproduce
| consistently - the journal becomes the little notebook just like
| the detective in a TV show. You pour into it every single clue,
| every bit of data. That process leads to you asking yourself
| certain questions or thinking of things to try to flush out the
| bug. This journaling is especially helpful during a crisis
| situation where it's easy to spin your wheels, panic, waste time,
| etc. - that methodical act of writing things down is calming and
| organizing.
| tvon_g wrote:
| I really wish I had more information about some concrete
| technical problems I've solved in the past. The problem I've
| often run into is that writing them down is tedious. I used to
| record myself on video using the native camera app on iOS but
| found that information just gets lost in those videos. That led
| me to create an app that allows me to record myself on video,
| then transcribes what I say and synthesis it using Chat GPT. I've
| called it Vournal.
|
| And if anybody wants to try it out you can download it here:
| https://apps.apple.com/us/app/vournal-ai-video-journal/id644...
|
| Or if you'd like free access ask me for a TestFlight invite :)
| mlady wrote:
| I've been recording myself driving in my car for years as sort
| of a journal, but never did anything with the videos. Will
| start using this!
| mlady wrote:
| any way to mass-import videos taken from the native iOS camera
| would be an amazing feature that I would pay $$$ for.
| bgribble wrote:
| I went to school as an EE and learned in college to keep written,
| dated lab notes in a notebook without removable pages (to be more
| credible as evidence).
|
| I did this for years in my earlier career... there's something
| really nice about using a pen and paper to write down ideas and
| sketches. I've always felt it was the "linearization" of moving
| your pen through making a series of marks, one at a time, that
| helps clarify the thinking process.
|
| Then I actually did get tangled up in a lawsuit, by shareholders
| against the execs of a startup I worked for, and had all my
| journals subpoena'ed. It was a harsh reminder that lab notes
| aren't really your own private sticky notes; if they are ever
| going to be used as evidence, they are better thought of as a
| continuous performance of Engineering Best Practices.
|
| I basically stopped writing paper notes then.
|
| I've started journaling my coding again, but electronically
| (mostly using plain text notes in files, with Johnny Decimal to
| keep them organized). It's just so helpful during the design and
| early implementation phase, or when working through a tricky bug
| hunt. But I usually delete them when I'm done with them.
| schneems wrote:
| > I basically stopped writing paper notes then.
|
| I'm curious why. Was there something in your notes that
| implicated you or was it more of a general "working under a
| microscope in public view feels stifling" or something else?
| PTOB wrote:
| Thank you for introducing me to Johnny Decimal!
| myth2018 wrote:
| I second this.
|
| Btw, I witness, in an almost daily basis, the power of a
| shared classification system based on numerical IDs/prefixes.
|
| My parents use a web app based on an old-school text user
| interface (the vendor translated the original Pascal code to
| a CGI-based web app). The multiple routines are identified by
| numbers, (kind of) following a certain organization logic.
| Routines can optionally be called directly by typing its ID
| instead of navigating menus.
|
| The team's communication and work-flow naturally organize
| around this classification method. The vendor's support staff
| also use the same language. "You can find this in 938, that
| in 835, and then check the overall status in 104". Repetition
| + predictability provided by the underlying classification
| logic quickly imprints those IDs in users' memory.
|
| Such a simple, ellegant system.
| jen729w wrote:
| Hey, Johnny here. Always happy to help, answer questions,
| give support. Glad you find it useful.
| bgribble wrote:
| yw, I think I originally came across it on HN :) It's not
| perfect, but it's pretty solid.
|
| The one way my personal system diverges from the original is
| that I have a 3-digit prefix before the 2-digit category ID.
| 001 is my personal recordkeeping other than creative projects
| and has its own category tree. Then 002-499 are creative
| personal projects (non-work software and music). Software and
| music projects each have their own category tree template.
| 500-999 are work-related; right now, 500 is non-software-
| project info related to my current employer (interview notes,
| admin stuff, blog posts, other writing) and 501-599 are major
| software projects. I am guessing 600-699 would be my next
| employer, 700-799 the next, etc.
| bbor wrote:
| This is interesting, I'd love to hear a bit of elaboration if
| you find the time; why delete your notes? Why do we care if
| they're used in a lawsuit against our bosses, assuming we're
| not doing anything illegal?
|
| I imagine I'm just being naive, because I've never worked in a
| small startup.
| bgribble wrote:
| For me, having to produce my journals was a reminder that
| holding on to my notes means that I might need to give a
| deposition or testify about them. Engaging with the court
| system in any way is just not something I care to do if I can
| avoid it. So I re-examined the value proposition of keeping
| written notes.
|
| If I was working in an environment where (for example)
| producing patentable inventions was part of the job, I would
| keep and retain solid lab notebooks in case they are needed
| to defend my employer's IP, and would write them every day
| with that purpose in mind. Likewise in a job where we have to
| follow ISO-style engineering processes in a regulated
| environment such as medical device software. That's not at
| all the same as keeping a journal of development for my own
| improvement... that's consciously creating an artifact so it
| can be produced on demand.
|
| If I just keep my garbage notes in garbage files that I
| delete, I can use them while they are relevant and sweep up
| after, just as if they were post-it notes.
| bbor wrote:
| Thanks for response, makes a lot of sense! I can't yet
| relate to the first reasons, but I definitely see the
| appeal of mentally marking working notes as "garbage". I
| find that trying to make working notes an artifact always
| leads to me getting distracted
| chinchilla2020 wrote:
| Even innocent trials and brainstorming can get you in to hot
| water. Some P.E.s in the Electrical Engineering field at my
| old company were known for keeping a good set of wikis,
| journal, and email lists. They had an internal sort of peer
| review system between our plants.
|
| An unrelated lawsuit was filed against the company by the
| state. A set of speculative statements in an email chain made
| by one EE about hypothetical measurement issues was taken as
| proof of company "knowledge" about inaccurate reporting.
| bbor wrote:
| I do this religiously, and would recommend two things above all
| else:
|
| - Keep the format and entry method simple above all else. I use
| Sublime Text to edit markdown files now, and have only had
| trouble with various more feature-rich options like Obsidian.
|
| - Write down what comes to you, and spend as little time as
| possible adhering to some format devised by you or some
| personality guru (like the ones discussed in this great post).
| You'd be surprised how easy it is to read back through less-
| organized notes, and if you don't experiment in the moment,
| you'll never find the set of
| rules/sections/formats/guidelines/etc. that work for you!
| omgmajk wrote:
| I keep a somewhat loose journal of stuff I do at work, mostly
| because I want to know how I did things. At home I keep a more
| rigorous journal of things, especially things I install or code.
| john-radio wrote:
| When I made the jump from tmux+vim to Doom Emacs, the learning
| curve was steep, and the only thing that made it manageable was
| to start a Google Sheet where I recorded questions that were
| bothering me and their answers, if/when I discovered the answer.
| It was a valuable process because the act of writing down the
| solution helped crystallize the knowledge in my brain, plus
| whenever I reviewed the spreadsheet, if a question remained open
| too long, I knew it was time to take the question to /r/emacs or
| to this forum.
|
| You can see the spreadsheet if you want! (But please don't spend
| any time chasing down answers for me; this is an old sheet and I
| don't have too many open questions about emacs right now).
|
| https://docs.google.com/spreadsheets/d/1BcEsENMSLmOfsjTORHLt...
| Syzygies wrote:
| Years ago I kept a journal of every bug, coding in pre-ANSI C. I
| figured that with care, I'd never make the same mistake twice.
|
| I found the list years later. Last entry: "Forgot to eat. Got
| sick."
___________________________________________________________________
(page generated 2023-06-12 23:01 UTC)