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.
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 ;)
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.
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.
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)
[...])))
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.
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.
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.
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?
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.
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.
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
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.
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.
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 ("most recent threads" is equivalent to "most recently updated thread")
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?
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.
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.
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.
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
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).
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!
> 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.
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!
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.
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.
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.
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.
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).
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.
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.
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.
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.
58 comments
[ 4.2 ms ] story [ 115 ms ] threadI 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.
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.
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.
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?
I imagine I'm just being naive, because I've never worked in a small startup.
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.
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.
Stolen, doing!
Demonstration of default settings: 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
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?
Or when I design an algorithm,I use pen and paper and keep it as a trace.
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.
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.
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...
I found the list years later. Last entry: "Forgot to eat. Got sick."
- 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!
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.
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
- 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.
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).
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/
[2]: https://brettterpstra.com/projects/na/
[3]: https://xwmx.github.io/nb/#home
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 :)
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.