I think this is great advice. One thing that I think is simultaneously trite and under-appreciated is the degree to which writing itself drives strong memory formation, even if the notes themselves aren’t particularly good or detailed. I’ve been keeping technical notebooks for about a decade now, and I’ve found that I can open up to almost any page and remember exactly what I was thinking when I scrawled on it. By contrast, things I write in Obsidian need much more context (i.e. detail) to remind me what I was thinking.
We have a strong culture of engineering notebooks in my org. I tried for a good 5 years — i carried one and probably filled up 5 of them.
But i went back to them maybe 5 times in all those years. And the effort of writing actually distracts me more than the effortless action of typing. Plus the search and backup functions.
Even in high school in the early 90s I typed up all my class notes because the act of transcribing my written scratch to typed notes cemented it in my memory — i remember the sensation of recalling something for a test by air typing.
I guess with this history, its just how Ive trained myself so I carry laptop every where I go and type on that, but I al jealous of some of the well crafted and illustrated notes of some peers — especially the ones with multicolor pens for differentiation.
One thing that has helped me keep to start keeping long-running notebooks (which I use as engineering notebooks at times, among other things) is to actually keep two: one for immediate notes that I treat as disposable, and then another for "permanent" stuff. The former is a little 3x5 pocket notebook that literally lives in my pocket (or beside my keyboard), and I can jot stuff down in whatever order or format is convenient at the time. When I have a bit of time, I go through and "reconcile" the smaller notebook with the larger one (a regular composition book) by copying over the relevant information and indexing it. I then cross off the pages in the pocket notebook so I'll know I've dealt with them. (FWIW this is inspired by the bookkeeping practice of keeping a "wastebook" or "journal" that is just a list of transactions as they happen, and later "posting" or reconciling them into one's ledgers.)
This has a couple benefits. First, you always get better work if you go through more than one draft. Second, the idea of something being in the "permanent" notebook forever can cause me to freeze up a bit, not wanting to "mess it up". Having a place where I can "stage" or draft my entries helps with this.
In my research I take notes exactly as described here. I use plain-text files, one per week, with dated sections using markdown-ish notation where convenient. Display is never a goal; approximately 80-char column plaintext is the target format.
I agree with other commenters here that typing gives me more flexibility, in particular when writing arguments. I’ll format each point as a bullet and rearrange the list until I’m satisfied with the flow.
The notebook is essential for recovering tidbits learned along the way, e.g. what tricky steps did I need to get that one dependency to build. Weekly notepads are coarse enough to search by memory and contain enough context to get oriented quickly when going back several months.
I found a similar blog post like this years ago at the start of my career and started keeping a Rhodia Webnotebook A5. I've got over a dozen now from all my years of work. Nice for nostalgia
Just wanted to flag the use of the little "jump back to where I was reading" links on the footnotes is a feature I'll be implementing and using on every footnote I ever write for the rest of my life now. Thank you!
I use Obsidian to record decisions, plan every day and take detailed notes. Very handy for recalling the nitty gritty for future reference be it performance reviews, writing blogs or updating my resume.
I was given this advice at university, but what I was always missing was what I was supposed to write down in them.
The post here mentions hypotheses, but I don't do experiments for the most part. It mentions writing down in the notebook before writing code, but I can't test my notes, I can't really send my notes for code review. I guess you could use it for design, but you'd lose all the advantages of word processing such as editing, links, context, etc.
I often have a scratch pad editor around with current working state in – that makes sense to me, but not on paper and that's not what's being proposed. I have also at times kept a logbook of what I've done, but it was very much an end of the day/week summary, not in the moment, not forward looking like this mentions.
The idea sounds great, but what is actually being written down?
Where do you write down your ideas for programs, lists of useful libraries/software, approaches to solving different problems, articles to read later?
Once in a while I hear a programmer say they don't keep notes of any kind and I have to assume they were blessed with photographic memories and perfect recall, because the rest of us are not so fortunate.
I use a notebook extensively for certain kinds of work and problems. I’ll point out specific ways that I use it to answer your questions.
> The post here mentions hypotheses, but I don't do experiments for the most part.
Debugging any hard bug is essentially making a series of hypotheses and testing them. I use a notebook to keep track and make notes when I’m knee-deep in some hairy bug.
> It mentions writing down in the notebook before writing code, but I can't test my notes, I can't really send my notes for code review.
I use a notebook primarily for design work, especially algorithmic design work.
It’s really handy for numerical stuff where I often want to transform some expression or equation and prove to myself that it’s equivalent or has certain properties.
It’s also handy for working through any algorithm where you’re manipulating a tree or a graph.
> I guess you could use it for design, but you'd lose all the advantages of word processing such as editing, links, context, etc.
I find it much faster to sketch the things I mentioned (especially diagrams!) with pen and paper when working through them. If I need to present the work or share it, I might scan the notes or I can polish them in a word processor or slide deck or whatever.
For what it’s worth, my background is in a computational science (not CS) and I do quite a lot of work on numerical and algorithmic problems that come up in actual hardware and sensors. I also like to work on compiler-y things in my spare time.
Ultimately you end up using tools that are useful for you. So none of this may have any value for your work. But hopefully it answers what someone might write in a notebook.
1. Choose the most low-friction solution you can get your hands on.
2. Write down everything you do, as you do it.
3. You can not be too detailed.
4. Write down your train of thought when you’re planning and designing your code.
5. Don't worry too much about making your notes look good.
6. Use a searchable text format.
7. Make your notes append-only.
8. Use your notes as a source for documentation, commit summaries and pull request descriptions.
9. Share your notes with your whole team.
10. Don’t make your notes public.
11. Learn from your mistakes.
I used to use HackMD but I have found Obsidian helps me better meet the criteria above (low-friction yet searchable).
I have learned the hard way, repeatedly, that forcing myself to write down a to-do list and notes on what I did actually makes me a better developer, even when I am in software engineering mode, not research mode. I make myself prioritize what to do, I retain better what I've learned, and I converge on solutions faster.
I've been using the "Zim desktop wiki" like this for years. I do recommend it as well...super handy to be able to go looking for my thoughts or snippets from 6 months ago. I can also use git to sync between my desktop and laptop because it's all text.
For my side projects I have a dev log and every day that I work on them I've gotten into the habit of writing "What I want to accomplish", "What I did", and "What's next", which all seems to capture my thoughts pretty well. I don't get super detailed on them, but I can look back at previous days to see what I should work on next and it helps me goal set better. Also helps me when I need to pause on my work for the day so I can pick it up later.
I'd have a hard time with a physical notebook. Speed and search are key.
My workspace is just a markdown file, with dates and work-in-progress (scripts, bug investigations, design notes, task lists...), by date (reversed), rolled up to month files. If something (non-code) bears remembering, it's normalized and published to others, or put into my own topic space (leaving the WIP notes).
The key feature is global search over all such files. I can find any activity and any topic in seconds, with a search-bar overview of all places where I addressed some subject. (As a result I tend to create unique names.)
As a discipline, speaking directly and constantly to future self does help establish more methodical approaches, reinforces context awareness (and avoid ratholes); I restart even small projects where I left off, and scale the number of projects I try. Somehow the act of writing provides a reflective time/instant boundary (think: clocks in a functional universe) that orients the work in time/relevance to avoid wasting time on things that matter less.
I have settled on a way to do append only notes by having a "journal" user on my xmpp server, and I take notes by sending them asciidoc formatted messages. I have been too lazy to do it so far, but I could extract the messages from the server and compile them into something more easily browsed.
This is maybe a bit of a tangent to this article,but I've tried so many pieces of tech over the years to replace pen & paper notebooks, mainly iPads and eInk based notetaking devices, like the Remarkable.
While I cannot find a concrete flaw with these things, with some of them working quite well, I just couldn't really get a feel for them - they always felt so tech-y and imprecise, that I always went back to an actual sheet of paper.
Another product design misconception I think a lot of companies make is the use of metal cases - metal feels high-end and durable as opposed to plastic I suppose, and with it being quite solid, manufacturers can make it thinner and lighter.
But it's uncomfortable to hold, and hard to manufacture complex shapes, which means these devices often end up in a case. Man I miss the 2000s when product design wasn't dead.
This is a timely article for me. I was consulting Joe Decuir's Engineering Notebooks just yesterday and wondered if these sorts of notebooks were a common thing or whether it was just Atari.
Joe Decuir was an engineer at Atari and was involved with the development of the 2600. His notebooks can be useful references for the 2600, even to this day.
I've been doing this more and more over the past year, but I just write on plain white paper and throw it away after the stack on my desk gets too big.
Like the author, I don't seem to ever need to read my old notes. Instead, it works wonders as a mental bucket of sorts and I've found paper to be extremely powerful for this. I tried doing this on a Surface Pro, for example, but it was significantly less enjoyable or effective.
Now with LLMs helping me write code, planning ahead on paper is even more useful.
I’ve been doing this for the past 15 years - writing “LAZYs”, started off as just .txt files, now .md. The nice thing with it now you can search through it easily or give it to Codex
73 comments
[ 0.21 ms ] story [ 70.1 ms ] threadI make notes while working and notes during meetings. Honestly most of it never gets read after a eay but I still do it.
Very few of my colleagues carry a notebook around. Those who do are not seen taking notes too often.
But i went back to them maybe 5 times in all those years. And the effort of writing actually distracts me more than the effortless action of typing. Plus the search and backup functions.
Even in high school in the early 90s I typed up all my class notes because the act of transcribing my written scratch to typed notes cemented it in my memory — i remember the sensation of recalling something for a test by air typing.
I guess with this history, its just how Ive trained myself so I carry laptop every where I go and type on that, but I al jealous of some of the well crafted and illustrated notes of some peers — especially the ones with multicolor pens for differentiation.
This has a couple benefits. First, you always get better work if you go through more than one draft. Second, the idea of something being in the "permanent" notebook forever can cause me to freeze up a bit, not wanting to "mess it up". Having a place where I can "stage" or draft my entries helps with this.
I agree with other commenters here that typing gives me more flexibility, in particular when writing arguments. I’ll format each point as a bullet and rearrange the list until I’m satisfied with the flow.
The notebook is essential for recovering tidbits learned along the way, e.g. what tricky steps did I need to get that one dependency to build. Weekly notepads are coarse enough to search by memory and contain enough context to get oriented quickly when going back several months.
The post here mentions hypotheses, but I don't do experiments for the most part. It mentions writing down in the notebook before writing code, but I can't test my notes, I can't really send my notes for code review. I guess you could use it for design, but you'd lose all the advantages of word processing such as editing, links, context, etc.
I often have a scratch pad editor around with current working state in – that makes sense to me, but not on paper and that's not what's being proposed. I have also at times kept a logbook of what I've done, but it was very much an end of the day/week summary, not in the moment, not forward looking like this mentions.
The idea sounds great, but what is actually being written down?
Once in a while I hear a programmer say they don't keep notes of any kind and I have to assume they were blessed with photographic memories and perfect recall, because the rest of us are not so fortunate.
> The post here mentions hypotheses, but I don't do experiments for the most part.
Debugging any hard bug is essentially making a series of hypotheses and testing them. I use a notebook to keep track and make notes when I’m knee-deep in some hairy bug.
> It mentions writing down in the notebook before writing code, but I can't test my notes, I can't really send my notes for code review.
I use a notebook primarily for design work, especially algorithmic design work.
It’s really handy for numerical stuff where I often want to transform some expression or equation and prove to myself that it’s equivalent or has certain properties.
It’s also handy for working through any algorithm where you’re manipulating a tree or a graph.
> I guess you could use it for design, but you'd lose all the advantages of word processing such as editing, links, context, etc.
I find it much faster to sketch the things I mentioned (especially diagrams!) with pen and paper when working through them. If I need to present the work or share it, I might scan the notes or I can polish them in a word processor or slide deck or whatever.
For what it’s worth, my background is in a computational science (not CS) and I do quite a lot of work on numerical and algorithmic problems that come up in actual hardware and sensors. I also like to work on compiler-y things in my spare time.
Ultimately you end up using tools that are useful for you. So none of this may have any value for your work. But hopefully it answers what someone might write in a notebook.
Sounds like your approach works for you.
Here's a similar post with more concrete advice on what to write: https://jamesmckay.net/2017/02/how-to-keep-lab-notes-as-a-so...
1. Choose the most low-friction solution you can get your hands on. 2. Write down everything you do, as you do it. 3. You can not be too detailed. 4. Write down your train of thought when you’re planning and designing your code. 5. Don't worry too much about making your notes look good. 6. Use a searchable text format. 7. Make your notes append-only. 8. Use your notes as a source for documentation, commit summaries and pull request descriptions. 9. Share your notes with your whole team. 10. Don’t make your notes public. 11. Learn from your mistakes.
I used to use HackMD but I have found Obsidian helps me better meet the criteria above (low-friction yet searchable).
I have learned the hard way, repeatedly, that forcing myself to write down a to-do list and notes on what I did actually makes me a better developer, even when I am in software engineering mode, not research mode. I make myself prioritize what to do, I retain better what I've learned, and I converge on solutions faster.
My workspace is just a markdown file, with dates and work-in-progress (scripts, bug investigations, design notes, task lists...), by date (reversed), rolled up to month files. If something (non-code) bears remembering, it's normalized and published to others, or put into my own topic space (leaving the WIP notes).
The key feature is global search over all such files. I can find any activity and any topic in seconds, with a search-bar overview of all places where I addressed some subject. (As a result I tend to create unique names.)
As a discipline, speaking directly and constantly to future self does help establish more methodical approaches, reinforces context awareness (and avoid ratholes); I restart even small projects where I left off, and scale the number of projects I try. Somehow the act of writing provides a reflective time/instant boundary (think: clocks in a functional universe) that orients the work in time/relevance to avoid wasting time on things that matter less.
While I cannot find a concrete flaw with these things, with some of them working quite well, I just couldn't really get a feel for them - they always felt so tech-y and imprecise, that I always went back to an actual sheet of paper.
Another product design misconception I think a lot of companies make is the use of metal cases - metal feels high-end and durable as opposed to plastic I suppose, and with it being quite solid, manufacturers can make it thinner and lighter.
But it's uncomfortable to hold, and hard to manufacture complex shapes, which means these devices often end up in a case. Man I miss the 2000s when product design wasn't dead.
Joe Decuir was an engineer at Atari and was involved with the development of the 2600. His notebooks can be useful references for the 2600, even to this day.
https://archive.org/details/JoeDecuirEngineeringNotebook1977
https://archive.org/details/JoeDecuirEngineeringNotebook1978
- memory/yyyy-mm-dd.md
- MEMORY.md
- SOUL.md
Like the author, I don't seem to ever need to read my old notes. Instead, it works wonders as a mental bucket of sorts and I've found paper to be extremely powerful for this. I tried doing this on a Surface Pro, for example, but it was significantly less enjoyable or effective.
Now with LLMs helping me write code, planning ahead on paper is even more useful.