8 ms·

The power of keeping a coding journal (2014)

179 points by jstrieb 3y ago

dukeofdoom 3y ago
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 3y ago
  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 ;)
uLogMicheal 3y ago
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.
impyamin 3y ago
"The coding journal doesn’t prevent me writing from writing bugs. " meta
FigurativeVoid 3y ago
I wouldn't call it a journal, put I keep a lot of notes for myself on tricky issues. More than once it has been really helpful figuring out an issue for myself, or I can just send the note to another person.
joshdick 3y ago
Shouldn't future work like this just go into the backlog of your ticketing system?
- macintux 3y ago
  > I want to emphasize that the coding journal is not a todo file or code comment. It contains things I have to think about not things I have to do. The author mentions that a lot of these will eventually end up in comments or elsewhere, but it’s nice to capture random thoughts without adding the friction of deciding where it should land, what priority the ticket should be, etc, etc is quite nice.
  - all2 3y ago
    This matches the spirit of Getting Things Done's "Inbox" quite well. The goal is to minimize friction for recording thoughts/ideas/todos that come into your head. You write them down and into the Inbox they go, to be sorted/dealt with at some later time.
    - onlypositive 3y ago
      Or never. I write notes throughout the day. Hardly ever search back in it. It's just to let me stop thinking about thing X while I'm working on thing Y. If X is important it'll come up again or show up in a ticket somewhere.
- cratermoon 3y ago
  In theory perhaps. In practice, if you're stuck using the likes Jira or ADO, the friction of getting something into the ticketing system is excessive. If you're using a ticketing system designed for programmers and not project managers, then maybe it could be organized for a flow like that.
bcrosby95 3y ago
I keep a devlog file. It's where most of my development related things go. I use it as a scratchpad as I do pretty much anything. If it gets too large, I move it into my "log" directory and start anew. I also keep a more synthesized "notes" folder.
cratermoon 3y ago
The link to jrnl provided in the article is broken. It seems to now be at <https://jrnl.sh https://jrnl.sh>
philsnow 3y ago
If you’re into emacs, org-capture is great for this kind of thing.
- smegsicle 3y ago
  what does your capture template look like, and where do you capture them to?
  - deleted 3y ago
    [deleted]
  - Zambyte 3y ago
    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 3y ago
    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) [...])))
- randoglando 3y ago
  What would be something similar for vim?
bgribble 3y ago
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 3y ago
  > 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 3y ago
  Thank you for introducing me to Johnny Decimal!
  - bgribble 3y ago
    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.
deleted 3y ago
[deleted]
gnuvince 3y ago
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.
- tommica 3y ago
  What an interesting idea - my goto has been personal wikis, but personal discussion board seems like a great choice!
- photoGrant 3y ago
  This is borderline genius! Thank you! Stolen, doing!
- laerios 3y ago
  This is exactly my use-case for a fossil repo with the built-in forum, with the default provided sorting. Fleeting notes get migrated as needed to Wiki pages (capability for which is also built-in). Demonstration of default settings: https://fossil-scm.org/forum/forum https://fossil-scm.org/forum/forum ("most recent threads" is equivalent to "most recently updated thread") Docs: https://fossil-scm.org/home/doc/trunk/www/forum.wiki https://fossil-scm.org/home/doc/trunk/www/forum.wiki
jasonpeacock 3y ago
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?
- 8note 3y ago
  Those Todo items only live for a day or two. It's ok to write them down, but write a new list imin a new page the next time you're doing something
aatd86 3y ago
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.
matsemann 3y ago
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.
velcrovan 3y ago
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 3y ago
  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.
Aperocky 3y ago
Shameless plug on the same subject if you are vim user fond of terminal: https://github.com/Aperocky/diarycli 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 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.
devrob 3y ago
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 https://github.com/aquaflamingo/devlogs
john-radio 3y ago
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/1BcEsENMSLmOfsjTORHLtYF5Cl-bcOyMC-VEgAygFeHQ/edit#gid=0 https://docs.google.com/spreadsheets/d/1BcEsENMSLmOfsjTORHLt...
Syzygies 3y ago
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."
bbor 3y ago
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!
- nonethewiser 3y ago
  > 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. Ive reached the same conclusion. I use my IDE (vscode) and markdown. Unstructured notes are easy to write, and I value that over discoverability. Its the same principle as nosql vs sql, or the same benefits of a datalake! I almost never go back and look at my notes, which I write per task. When I do I use the VSCode search. Whats more important for me is zero friction to writing them down. Its more of a “working memory “ dump than a document to share or read again. I actually noticed the same principle at play with arc browser. I hated thinking about “where does this tab belong” every time I wanted to open a new one or put things side by side.
  - randoglando 3y ago
    How does arc browser solve that problem?
semireg 3y ago
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!
sureglymop 3y ago
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.
simonw 3y ago
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 https://github.com/simonw/public-notes/issues/1
- jjice 3y ago
  Very cool. Your notes seem very high quality and the fact that they'll be indexed by search engines is great for other people.
omgmajk 3y ago
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.
dbrueck 3y ago
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.
- Metaluim 3y ago
  I do something similar to your first approach just as I'm about to context switch (either because the day has ended or I have to work on something else). I write a small summary of what I was doing and what were my next steps at the time, and I write this either directly in the code, in paper or sometimes in a text file. I call them ENDSNAPs (end snapshots).
- alwillis 3y ago
  A few tools I've come across that I've used. Doing [1] by Brett Terspstra; "A command line tool for keeping track of what you’re doing and tracking what you’ve done." NA [2] (Next Action) also by Brett Terpstra; "A command line tool for adding and listing per-project todos." nb [3] is "a command line and local web note‑taking, bookmarking, archiving, and knowledge base application" nb supports multiple notebooks, Git-based version control and a bunch of other things [1]: https://brettterpstra.com/projects/doing/ https://brettterpstra.com/projects/doing/ [2]: https://brettterpstra.com/projects/na/ https://brettterpstra.com/projects/na/ [3]: https://xwmx.github.io/nb/#home https://xwmx.github.io/nb/#home
ArcMex 3y ago
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.
tvon_g 3y ago
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/id6447381102 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 3y ago
  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 3y ago
  any way to mass-import videos taken from the native iOS camera would be an amazing feature that I would pay $$$ for.
greyman 3y ago
Might I ask those who does this - do you use one "global" journal for everything development related, or it is per-project?
- HumblyTossed 3y ago
  I use a global journal. Just a wirebound notebook to jot notes. I write down user story or bug fix ids if I'm working on those, if not I'll try and make some sort of title to what I'm doing. I find it is handy when a problem comes up, I can say I fixed the issue, here's what I did and why. Or if it's new development and I'm asked why didn't I do blah, I can show that I did and here are the results and why I chose alt-blah. Mostly it's a memory tool.
pksebben 3y ago
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.
justinlloyd 3y ago
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 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/ https://justinlloyd.li/blog/word-search-game/ (1978) and https://justinlloyd.li/blog/word-search-game-part-two/ https://justinlloyd.li/blog/word-search-game-part-two/ and https://justinlloyd.li/blog/better-date-format/ https://justinlloyd.li/blog/better-date-format/ (1979) are some samples, though I didn't call them lab notes back then.
HybridCurve 3y ago
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.
nonethewiser 3y ago
I more or less do this for every task. Link to task, todo list, useful links, design decisions, etc. The trick for me is giving myself permission to be messy and imperfect. The todo list evolves over time and often misses things or ends up containing more than necessary. Sometimes I assert things that dont end up being that relevant. Often the design decisions are a bit handwavey. This is all ok because 90% of the value is simply writing it down as a means of thinking. The other useful aspect is keeping track of loose ends (“make sure to use test this edge case” for example) and very occasionally a search of my notes directory unearths a useful piece of information Ive saved. But it is not a clear and concise document that can easily be read start to finish for a complete understanding of the development process and state of my branch. It just cant be (at least for me) because it would just take too much work and its already serving the purpose of being a thought exercise, unstructured memory store, and aid for context switching.
perfmode 3y ago
I prefer inline TODO and FIXME comments
wjgilmore 3y ago
I’ve been keeping a daily technical log for about 12 years now. It’s nothing fancy, managed in a series of Markdown files, one file per month. At last check when converted to a PDF it was somewhere north of 5,000 pages. On quite a few occasions it has saved me several hours (at least) of debugging when revisiting or troubleshooting some obscure code or infrastructure change I had previously made. When not sure of the particular month/year I will just grep for all occurrences of a related term until something jogs my memory. Highly recommended.
kreelman 3y ago
jrnl link at the top of the article doesn't exist.... Is this the correct link ? https://github.com/jrnl-org/jrnl https://github.com/jrnl-org/jrnl Nice idea. I like org-mode for ...nearly everything.... This looks good for the command line. Thanks

179 points by jstrieb 3y ago

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 3y ago
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 ;)

uLogMicheal 3y ago

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.

impyamin 3y ago

"The coding journal doesn’t prevent me writing from writing bugs. " meta

FigurativeVoid 3y ago

I wouldn't call it a journal, put I keep a lot of notes for myself on tricky issues. More than once it has been really helpful figuring out an issue for myself, or I can just send the note to another person.

joshdick 3y ago

Shouldn't future work like this just go into the backlog of your ticketing system?

macintux 3y ago
> I want to emphasize that the coding journal is not a todo file or code comment. It contains things I have to think about not things I have to do. The author mentions that a lot of these will eventually end up in comments or elsewhere, but it’s nice to capture random thoughts without adding the friction of deciding where it should land, what priority the ticket should be, etc, etc is quite nice.
- all2 3y ago
  This matches the spirit of Getting Things Done's "Inbox" quite well. The goal is to minimize friction for recording thoughts/ideas/todos that come into your head. You write them down and into the Inbox they go, to be sorted/dealt with at some later time.
  - onlypositive 3y ago
    Or never. I write notes throughout the day. Hardly ever search back in it. It's just to let me stop thinking about thing X while I'm working on thing Y. If X is important it'll come up again or show up in a ticket somewhere.
cratermoon 3y ago
In theory perhaps. In practice, if you're stuck using the likes Jira or ADO, the friction of getting something into the ticketing system is excessive. If you're using a ticketing system designed for programmers and not project managers, then maybe it could be organized for a flow like that.

bcrosby95 3y ago

I keep a devlog file. It's where most of my development related things go. I use it as a scratchpad as I do pretty much anything. If it gets too large, I move it into my "log" directory and start anew. I also keep a more synthesized "notes" folder.

cratermoon 3y ago

The link to jrnl provided in the article is broken. It seems to now be at <https://jrnl.sh https://jrnl.sh>

philsnow 3y ago

If you’re into emacs, org-capture is great for this kind of thing.

smegsicle 3y ago
what does your capture template look like, and where do you capture them to?
- deleted 3y ago
  [deleted]
- Zambyte 3y ago
  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 3y ago
  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) [...])))
randoglando 3y ago
What would be something similar for vim?

bgribble 3y ago

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 3y ago
> 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 3y ago
Thank you for introducing me to Johnny Decimal!
- bgribble 3y ago
  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.

deleted 3y ago

[deleted]

gnuvince 3y ago

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.

tommica 3y ago
What an interesting idea - my goto has been personal wikis, but personal discussion board seems like a great choice!
photoGrant 3y ago
This is borderline genius! Thank you! Stolen, doing!
laerios 3y ago
This is exactly my use-case for a fossil repo with the built-in forum, with the default provided sorting. Fleeting notes get migrated as needed to Wiki pages (capability for which is also built-in). Demonstration of default settings: https://fossil-scm.org/forum/forum https://fossil-scm.org/forum/forum ("most recent threads" is equivalent to "most recently updated thread") Docs: https://fossil-scm.org/home/doc/trunk/www/forum.wiki https://fossil-scm.org/home/doc/trunk/www/forum.wiki

jasonpeacock 3y ago

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?

8note 3y ago
Those Todo items only live for a day or two. It's ok to write them down, but write a new list imin a new page the next time you're doing something

aatd86 3y ago

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.

matsemann 3y ago

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.

velcrovan 3y ago

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 3y ago
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.

Aperocky 3y ago

Shameless plug on the same subject if you are vim user fond of terminal: https://github.com/Aperocky/diarycli 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 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.

devrob 3y ago

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 https://github.com/aquaflamingo/devlogs

john-radio 3y ago

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/1BcEsENMSLmOfsjTORHLtYF5Cl-bcOyMC-VEgAygFeHQ/edit#gid=0 https://docs.google.com/spreadsheets/d/1BcEsENMSLmOfsjTORHLt...

Syzygies 3y ago

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."

bbor 3y ago

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!

nonethewiser 3y ago
> 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. Ive reached the same conclusion. I use my IDE (vscode) and markdown. Unstructured notes are easy to write, and I value that over discoverability. Its the same principle as nosql vs sql, or the same benefits of a datalake! I almost never go back and look at my notes, which I write per task. When I do I use the VSCode search. Whats more important for me is zero friction to writing them down. Its more of a “working memory “ dump than a document to share or read again. I actually noticed the same principle at play with arc browser. I hated thinking about “where does this tab belong” every time I wanted to open a new one or put things side by side.
- randoglando 3y ago
  How does arc browser solve that problem?

semireg 3y ago

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!

sureglymop 3y ago

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.

simonw 3y ago

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 https://github.com/simonw/public-notes/issues/1

jjice 3y ago
Very cool. Your notes seem very high quality and the fact that they'll be indexed by search engines is great for other people.

omgmajk 3y ago

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.

dbrueck 3y ago

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.

Metaluim 3y ago
I do something similar to your first approach just as I'm about to context switch (either because the day has ended or I have to work on something else). I write a small summary of what I was doing and what were my next steps at the time, and I write this either directly in the code, in paper or sometimes in a text file. I call them ENDSNAPs (end snapshots).
alwillis 3y ago
A few tools I've come across that I've used. Doing [1] by Brett Terspstra; "A command line tool for keeping track of what you’re doing and tracking what you’ve done." NA [2] (Next Action) also by Brett Terpstra; "A command line tool for adding and listing per-project todos." nb [3] is "a command line and local web note‑taking, bookmarking, archiving, and knowledge base application" nb supports multiple notebooks, Git-based version control and a bunch of other things [1]: https://brettterpstra.com/projects/doing/ https://brettterpstra.com/projects/doing/ [2]: https://brettterpstra.com/projects/na/ https://brettterpstra.com/projects/na/ [3]: https://xwmx.github.io/nb/#home https://xwmx.github.io/nb/#home

ArcMex 3y ago

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.

tvon_g 3y ago

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/id6447381102 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 3y ago
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 3y ago
any way to mass-import videos taken from the native iOS camera would be an amazing feature that I would pay $$$ for.

greyman 3y ago

Might I ask those who does this - do you use one "global" journal for everything development related, or it is per-project?

HumblyTossed 3y ago
I use a global journal. Just a wirebound notebook to jot notes. I write down user story or bug fix ids if I'm working on those, if not I'll try and make some sort of title to what I'm doing. I find it is handy when a problem comes up, I can say I fixed the issue, here's what I did and why. Or if it's new development and I'm asked why didn't I do blah, I can show that I did and here are the results and why I chose alt-blah. Mostly it's a memory tool.

pksebben 3y ago

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.

justinlloyd 3y ago

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 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/ https://justinlloyd.li/blog/word-search-game/ (1978) and https://justinlloyd.li/blog/word-search-game-part-two/ https://justinlloyd.li/blog/word-search-game-part-two/ and https://justinlloyd.li/blog/better-date-format/ https://justinlloyd.li/blog/better-date-format/ (1979) are some samples, though I didn't call them lab notes back then.

HybridCurve 3y ago

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.

nonethewiser 3y ago

I more or less do this for every task. Link to task, todo list, useful links, design decisions, etc. The trick for me is giving myself permission to be messy and imperfect. The todo list evolves over time and often misses things or ends up containing more than necessary. Sometimes I assert things that dont end up being that relevant. Often the design decisions are a bit handwavey. This is all ok because 90% of the value is simply writing it down as a means of thinking. The other useful aspect is keeping track of loose ends (“make sure to use test this edge case” for example) and very occasionally a search of my notes directory unearths a useful piece of information Ive saved. But it is not a clear and concise document that can easily be read start to finish for a complete understanding of the development process and state of my branch. It just cant be (at least for me) because it would just take too much work and its already serving the purpose of being a thought exercise, unstructured memory store, and aid for context switching.

perfmode 3y ago

I prefer inline TODO and FIXME comments

wjgilmore 3y ago

I’ve been keeping a daily technical log for about 12 years now. It’s nothing fancy, managed in a series of Markdown files, one file per month. At last check when converted to a PDF it was somewhere north of 5,000 pages. On quite a few occasions it has saved me several hours (at least) of debugging when revisiting or troubleshooting some obscure code or infrastructure change I had previously made. When not sure of the particular month/year I will just grep for all occurrences of a related term until something jogs my memory. Highly recommended.

kreelman 3y ago

jrnl link at the top of the article doesn't exist.... Is this the correct link ? https://github.com/jrnl-org/jrnl https://github.com/jrnl-org/jrnl Nice idea. I like org-mode for ...nearly everything.... This looks good for the command line. Thanks