I didn't find note-taking particularly useful until I started keeping everything in a single notebook with dated pages.
This worked a lot better than (for example) trying to organise notes by category - it's often easier to remember when you were working on something than how you categorised it, and once you know roughly when, you can find it by binary search
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?
I'm a scientist. In the science world, the traditional lab notebook contained a narrative of what you were doing. You're kind of thinking out loud into it.
One measure of a good notebook is if it contains sufficient information that you don't have to repeat work only because you can't figure out what you did. There are other good reasons for repeating things of course.
My spouse is a lab scientist, and I've seen her meticulous notebooks. She was telling me just last week that one of her experiments produced a puzzling result. The next day she said: "I figured it out from my notebook. I skipped a step that was in the procedure."
There was a time when a notebook was also a legal document, and so there was a criterion of whether it would stand up in court as proof that you had invented something. Could a "person skilled in the art" replicate your work based on your notebook? My dad told me that his notebooks were regularly reviewed and witnessed.
The legal issues have changed, since the patent system has switched to the "first to file" rule. My employer got rid of its formal notebook policy when this change came through.
My problem with physical notebooks is that a great deal of my work is computational, and I automate things. In my case, the best form for recording my work is in fact a Jupyter notebook. On the other hand, I come from a family of chemists, and taking electronic notes in a "wet" chemistry lab is often impractical.
(Note that this is why Jupyter and Wolfram use the word "notebook" for their interface format)
> There was a time when a notebook was also a legal document
This is still the case in certain fields like policing where, in the United Kingdom at least, an officer's pocket notebook is an important document, albeit with some police forces now moving to electronic solutions for this: https://en.wikipedia.org/wiki/Police_notebook
I also keep a 'lab notebook', but I must admit that a lot of what I used to document in my notes (setting up software/compiling 3rd party deps) I now document in code (scripts, devops, etc).
I still find lots of value in keeping notes though! And sometimes miss it when I didn't keep notes.
I'm pretty sure it works very differently for different people so you have to figure out your own process. I've tried different things but at the end of the day, I simply have a notebook next to my laptop/in my laptop bag and write down everything in freeform text. No index, no bullet points and things like that. I put a date and start writing. I'll usually do some TODOs as checklists to get them out of my brain and bothering me at the start of the day but only big items, not each and every step. It's a mix of work and private things. Just writing stuff down is helpful for me, even if I never reference it again.
I do use the Feynman Technique if I come across something interesting and try to explain it on paper. So if I was using it just for work, I'd probably do that. Something like "Spec driven development (Github Spec Kit and similar toolkits) is essentially a bunch of md files that provide more context for agents. There are some scripts that provide scaffolding, having agents write the md uses a lot of tokens so writing them manually after the scaffold is generated makes more sense. Try with a small project."
I picked up bullet journaling a few years back and that’s how I track my work:
o Sales meeting with Foo Corp
- Suggested to Sam that we use PostgreSQL
- Made us $X by doing $Y (star drawing)
. Fix a thing
/ In the process of fixing a thing
X Done fixing the thing
And that’s about it. I write this in an epaper notebook (Supernote Nomad) that I take everywhere in the office. At a glance I can tell you what I’m working on, what I did, and who I told what. And when I’m writing my annual self-review, I can search it for the star drawings to know what I can brag about.
I specifically do this instead of an iPad because I found it vastly less distracting during meetings. I tend to leave it laying there while I look at the speakers and pay attention, rather than just checking Slack really quickly, and oh, better look at my email, etc.
This is salve for my ADHD-scalded mind.
I don't have a full-blown notebook, but I keep task notes in individual text files. A sample text might be:
- Fixing broken test: (full ci link)
- seems to be repo foo, target //bar:baz, subtest TestSomethingNice. Error: (30 lines of stack trace here)
- git checkout 0ead3f820da34812089
- trying locally: bazel test //bar:baz
- command failed, error: (relevant error here)
- turns out I need to set a config, reference: (wiki link here)
- trying: bazel test --config=green //bar:baz
- problem reproduces 5 times in a row, seems like 100% fail rate
- source file location: source/bar/baz.cc
- theory: baz is broken from recent dependency bump. Reverting commit 987afd
- result: the error is different now (more error text)
etc.. etc...
This is actually super handy for a complex problem. No need to wonder "did I see the error before?" or "wait, when I was trying that thing, did I see that message as well?" or "how do I reproduce a bug again?". No keeping dozens of tabs open so you can copy a few words from each of them. When later talking to someone, you can refer to your notes.
For me, it helps to slow down my thoughts and aides deep work. I draw diagrams, connect blurbs with arrows, and “link” to other page numbers.
This is still missing the "what" for me. What do you write down about the work?
Is it a plan for what you're about to work on? Is it a breakdown? Is it facts you learn as you work through something? Is it a minute by minute journal of what you've done? Is it just interesting details? Is it to-dos? Is it opinions you're trying to clarify?
Diagrams I get, my desk is covered in scribbled diagrams to help me visualise something or communicate it to a colleague.
For me, if it's worth thinking about it, it's worth writing it down. Doesn't matter if it's a todo list I just came up with, a system diagram, whatever I am currently working on, or thoughts on a human interaction I just witnessed. The act of writing it down guides me in my thinking.
Frankly, at the beginning? Anything you feel like. You can start, perhaps, with Just a title of what you're doing, pomodoros style.
Maybe a note of something you thought but couldn't follow up on that moment.
Diagrams are good. Much easier to think and much better and faster doing by hand. I always get distracted by the tool when I'm drawing in a computer. Even artist-modd
I also make bullet points of general ideas that I'm trying to accomplish.
Doodles.
Important thing is, don't fret. Over time you'll find how it works for you.
I really only find it useful when I'm investigating or troubleshooting some system I'm not familiar with.
A stupid yet accurate analogy is I turn up the log level for my brain lol
It's basically just a log file of everything I did and the result so I can pick it back up later, plus I include timestamps which helps me realize when I'm spinning my wheels for too long.
For building stuff, scribbling diagrams and flows is more useful if I need to work out something complex.
Every time you look up something on StackOverflow, refer to the API docs, or refer back to the ticket, use case, or requirements document, make a note of your question and the answer. Even when you stop typing to take a break for a moment, or after pushing code while you wait for the ci/cd pipeline, note down where you are and your last action or change.
Every time you start to write a TODO comment, make a note instead, or also.
Consider Kent’s Beck’s recommendation to write down every decision you make.
Making note of your question AND answer sounds like an excellent way to both remember and cut down on tabs.
> 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 think generally it's more about sketching the high level structure of the code. I will routinely write things like :
documents = ...
by_client = documents.group_by(client)
for client, doc_set in by_client:
for doc in doc_set: csv.write(doc)
Not at all following the actual APIs I use, but I can fill in the blanks when getting the code in place.
The above is very simple, of course, usually I'm working through something where I just want to play through what pieces of data I might or might be missing
I've tried that, but my brain is just going "why are you writing about doing the thing instead of, you know, DOING THE THING"?
I vastly prefer just making a working skeleton and filling that with actual code as I progress.
The book The Thinker's Toolkit: 14 Powerful Techniques for Problem Solving by Morgan Jones gives you a catalog of structured techniques for problem solving which you can use in your own writing.
Addendum to the above book's catalog would be "Decision Tables" (useful for all types of decision-making and not just software engineering); How to Use a Decision Table Methodology to Analyze Complex Conditional Actions Requirements in Software Development - https://www.methodsandtools.com/archive/archive.php?id=39
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.
On a side note, whenever I get a new journal (paper or electronic), my very first step is to draw a crappy cover on the first page. That’s easy for my because I lack the skill to draw a nice one. This kinda “breaks the seal” for me. It’s slightly ugly now, causing me to not feel bad about anything else I put in it afterward.
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 wonder if this sort of thing belings to a certain kind of organisation, or type of career. I can certainly see the value of "we have all of <brilliant engineer's> technical notes going back 43 years!" but in my experience, it's rare to meet a "brilliant engineer" who'll stay in one position for even a decade.
Personally, I've been in many 2-15 year employments where I made copious notes - but I did so in whatever wiki my department was using. I've never had the opportinity (or, for that matter, much desire) to bring those notes with me to the next position, as they were (a) specific to that place or task, and (b) quite certainly proprietary (if far from high-value industrial secrets). Detailed notes on the inner workings of an in-house framework, or end-to-end credit card processing flow, just aren't that relevant when your next role is steward of a 25-year-old national tax reporting platform.
I've done a few blog posts, but haven't generally felt the need to share my brilliant thoughts with the greater world, those were just my personal musings (as is this piece right here).
Don't get me wrong, I'd love to _be_ in a position where such long-term usefulness was expected.
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.
The big advantage of split keyboards is that a notebook fits nicely in-between the halves.
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.
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.
> under-appreciated is the degree to which writing itself drives strong memory formation, even if the notes themselves aren’t particularly good or detailed.
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 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.
Same for me. I also make extensive use of adding links to anything relevant. Spent a bunch of time discussing something in a slack thread: link it. Read some documentation: link it. Had a chat with an llm in a chat window: link it. Writing notes about how a bunch of code works : link to the functions. For this last one I've registered a custom vim:// URL scheme on my system which lets me link to a symbol within a given file, and when clicked focuses the relevant tmux window and navigates the relevant vim instance (using named pipes) to the symbol, or opens a fresh one if not already open.
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!
How long before people realize that they too have limited context length and adopt:
- memory/yyyy-mm-dd.md
- MEMORY.md
- SOUL.md
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.
Is an engineering notebook a specific kind of notebook? Google has a lot of results for "engineering notebook" but they seem to be all expensive fancy notebooks that have thin gridded paper
From the article,
> I'm not talking about a specific kind of paper notebook.
So no. Just a regular old paper notebook. Any kind will do.
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
I do the same thing, but with a Markdown file which I add a section to every day in a roughly append-only fashion
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.
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.
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.
I use a physical notebook but not really an engeneering notebook as described here.
I 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.
Almost all my paper notes these days are write-only media.
The benefit is not the artifact itself, but the immediate act of formalizing the idea, emphasizing its importance, and being mindful/attentive to what's going on.
Right. I am not sure why people have a hard time understanding this.
You almost always remember more of what you have consciously written down by hand than by typing. You can write as little or as much as you see fit; the point is that the conscious involvement of "whole body and mind" in the act of writing enforces mental discipline, helps find inter-disciplinary patterns and in general, is an aid to thinking.
Finally, if you look at any of the great Scientists, almost all of them wrote prodigiously viz. Letters/Papers/Books/etc. I am quite convinced that this was one important factor in the development of their greatness.
My personal role model for writing is of course Edsger Dijkstra :-)
Surprised it’s not mentioned, but important for the sake of patents too
> Surprised it’s not mentioned, but important for the sake of patents too
Is this still true these days? I thought the US moved to first-to-file in the early 2010s.
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.
Interesting. I use a paper notebook to but it's the opposite of detailed. I use one when I have several ideas in my head and I need to get them out before I forget some, or when I need to figure something out that's a wee bit too complicated to keep all the bits and bobbles in my brain-RAM.
But I write down just enough to offload the memory to paper. They're literal notes. Just enough so that I can remember what I was on about earlier. But probably not detailed enough I could come back in a couple months and recollect the rest of the details. What's the point in that anyway? These are things I intend to act on. Once I commit them to code, then the code becomes the source of truth.
100% i've been using paper notebooks since I started coding
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
I do this but instead in a google doc. Even better because I can use LLM's to query it aftewards.
For me, this helps in getting clarity. I do it especially during meetings it helps me think criticallyb- talk just flows by otherwise.
Human journalctl. Probably a good habit to try. Especially with an LLM to search and aggregate it later.
I didn't find note-taking particularly useful until I started keeping everything in a single notebook with dated pages. This worked a lot better than (for example) trying to organise notes by category - it's often easier to remember when you were working on something than how you categorised it, and once you know roughly when, you can find it by binary search
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?
I'm a scientist. In the science world, the traditional lab notebook contained a narrative of what you were doing. You're kind of thinking out loud into it.
One measure of a good notebook is if it contains sufficient information that you don't have to repeat work only because you can't figure out what you did. There are other good reasons for repeating things of course.
My spouse is a lab scientist, and I've seen her meticulous notebooks. She was telling me just last week that one of her experiments produced a puzzling result. The next day she said: "I figured it out from my notebook. I skipped a step that was in the procedure."
There was a time when a notebook was also a legal document, and so there was a criterion of whether it would stand up in court as proof that you had invented something. Could a "person skilled in the art" replicate your work based on your notebook? My dad told me that his notebooks were regularly reviewed and witnessed.
The legal issues have changed, since the patent system has switched to the "first to file" rule. My employer got rid of its formal notebook policy when this change came through.
My problem with physical notebooks is that a great deal of my work is computational, and I automate things. In my case, the best form for recording my work is in fact a Jupyter notebook. On the other hand, I come from a family of chemists, and taking electronic notes in a "wet" chemistry lab is often impractical.
(Note that this is why Jupyter and Wolfram use the word "notebook" for their interface format)
> There was a time when a notebook was also a legal document
This is still the case in certain fields like policing where, in the United Kingdom at least, an officer's pocket notebook is an important document, albeit with some police forces now moving to electronic solutions for this: https://en.wikipedia.org/wiki/Police_notebook
I also keep a 'lab notebook', but I must admit that a lot of what I used to document in my notes (setting up software/compiling 3rd party deps) I now document in code (scripts, devops, etc).
I still find lots of value in keeping notes though! And sometimes miss it when I didn't keep notes.
I'm pretty sure it works very differently for different people so you have to figure out your own process. I've tried different things but at the end of the day, I simply have a notebook next to my laptop/in my laptop bag and write down everything in freeform text. No index, no bullet points and things like that. I put a date and start writing. I'll usually do some TODOs as checklists to get them out of my brain and bothering me at the start of the day but only big items, not each and every step. It's a mix of work and private things. Just writing stuff down is helpful for me, even if I never reference it again.
I do use the Feynman Technique if I come across something interesting and try to explain it on paper. So if I was using it just for work, I'd probably do that. Something like "Spec driven development (Github Spec Kit and similar toolkits) is essentially a bunch of md files that provide more context for agents. There are some scripts that provide scaffolding, having agents write the md uses a lot of tokens so writing them manually after the scaffold is generated makes more sense. Try with a small project."
I picked up bullet journaling a few years back and that’s how I track my work:
o Sales meeting with Foo Corp
- Suggested to Sam that we use PostgreSQL
- Made us $X by doing $Y (star drawing)
. Fix a thing
/ In the process of fixing a thing
X Done fixing the thing
And that’s about it. I write this in an epaper notebook (Supernote Nomad) that I take everywhere in the office. At a glance I can tell you what I’m working on, what I did, and who I told what. And when I’m writing my annual self-review, I can search it for the star drawings to know what I can brag about.
I specifically do this instead of an iPad because I found it vastly less distracting during meetings. I tend to leave it laying there while I look at the speakers and pay attention, rather than just checking Slack really quickly, and oh, better look at my email, etc.
This is salve for my ADHD-scalded mind.
I don't have a full-blown notebook, but I keep task notes in individual text files. A sample text might be:
- Fixing broken test: (full ci link)
- seems to be repo foo, target //bar:baz, subtest TestSomethingNice. Error: (30 lines of stack trace here)
- git checkout 0ead3f820da34812089
- trying locally: bazel test //bar:baz
- command failed, error: (relevant error here)
- turns out I need to set a config, reference: (wiki link here)
- trying: bazel test --config=green //bar:baz
- problem reproduces 5 times in a row, seems like 100% fail rate
- source file location: source/bar/baz.cc
- theory: baz is broken from recent dependency bump. Reverting commit 987afd
- result: the error is different now (more error text)
etc.. etc...
This is actually super handy for a complex problem. No need to wonder "did I see the error before?" or "wait, when I was trying that thing, did I see that message as well?" or "how do I reproduce a bug again?". No keeping dozens of tabs open so you can copy a few words from each of them. When later talking to someone, you can refer to your notes.
For me, it helps to slow down my thoughts and aides deep work. I draw diagrams, connect blurbs with arrows, and “link” to other page numbers.
This is still missing the "what" for me. What do you write down about the work?
Is it a plan for what you're about to work on? Is it a breakdown? Is it facts you learn as you work through something? Is it a minute by minute journal of what you've done? Is it just interesting details? Is it to-dos? Is it opinions you're trying to clarify?
Diagrams I get, my desk is covered in scribbled diagrams to help me visualise something or communicate it to a colleague.
For me, if it's worth thinking about it, it's worth writing it down. Doesn't matter if it's a todo list I just came up with, a system diagram, whatever I am currently working on, or thoughts on a human interaction I just witnessed. The act of writing it down guides me in my thinking.
Frankly, at the beginning? Anything you feel like. You can start, perhaps, with Just a title of what you're doing, pomodoros style.
Maybe a note of something you thought but couldn't follow up on that moment.
Diagrams are good. Much easier to think and much better and faster doing by hand. I always get distracted by the tool when I'm drawing in a computer. Even artist-modd
I also make bullet points of general ideas that I'm trying to accomplish.
Doodles.
Important thing is, don't fret. Over time you'll find how it works for you.
I really only find it useful when I'm investigating or troubleshooting some system I'm not familiar with.
A stupid yet accurate analogy is I turn up the log level for my brain lol
It's basically just a log file of everything I did and the result so I can pick it back up later, plus I include timestamps which helps me realize when I'm spinning my wheels for too long.
For building stuff, scribbling diagrams and flows is more useful if I need to work out something complex.
Every time you look up something on StackOverflow, refer to the API docs, or refer back to the ticket, use case, or requirements document, make a note of your question and the answer. Even when you stop typing to take a break for a moment, or after pushing code while you wait for the ci/cd pipeline, note down where you are and your last action or change.
Every time you start to write a TODO comment, make a note instead, or also.
Consider Kent’s Beck’s recommendation to write down every decision you make.
Making note of your question AND answer sounds like an excellent way to both remember and cut down on tabs.
> 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 think generally it's more about sketching the high level structure of the code. I will routinely write things like :
Not at all following the actual APIs I use, but I can fill in the blanks when getting the code in place.The above is very simple, of course, usually I'm working through something where I just want to play through what pieces of data I might or might be missing
I've tried that, but my brain is just going "why are you writing about doing the thing instead of, you know, DOING THE THING"?
I vastly prefer just making a working skeleton and filling that with actual code as I progress.
You are overthinking it.
See my comment here - https://news.ycombinator.com/item?id=46986532
Also see a concrete example of an Engineering Notebook from a time when they were common, posted by user JetSetIlly here - https://news.ycombinator.com/item?id=46985832
On What and How to Write:
The book The Thinker's Toolkit: 14 Powerful Techniques for Problem Solving by Morgan Jones gives you a catalog of structured techniques for problem solving which you can use in your own writing.
Addendum to the above book's catalog would be "Decision Tables" (useful for all types of decision-making and not just software engineering); How to Use a Decision Table Methodology to Analyze Complex Conditional Actions Requirements in Software Development - https://www.methodsandtools.com/archive/archive.php?id=39
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.
On a side note, whenever I get a new journal (paper or electronic), my very first step is to draw a crappy cover on the first page. That’s easy for my because I lack the skill to draw a nice one. This kinda “breaks the seal” for me. It’s slightly ugly now, causing me to not feel bad about anything else I put in it afterward.
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.
https://archive.org/details/JoeDecuirEngineeringNotebook1977
https://archive.org/details/JoeDecuirEngineeringNotebook1978
Nice!
Thanks for posting this find.
I wonder if this sort of thing belings to a certain kind of organisation, or type of career. I can certainly see the value of "we have all of <brilliant engineer's> technical notes going back 43 years!" but in my experience, it's rare to meet a "brilliant engineer" who'll stay in one position for even a decade.
Personally, I've been in many 2-15 year employments where I made copious notes - but I did so in whatever wiki my department was using. I've never had the opportinity (or, for that matter, much desire) to bring those notes with me to the next position, as they were (a) specific to that place or task, and (b) quite certainly proprietary (if far from high-value industrial secrets). Detailed notes on the inner workings of an in-house framework, or end-to-end credit card processing flow, just aren't that relevant when your next role is steward of a 25-year-old national tax reporting platform.
I've done a few blog posts, but haven't generally felt the need to share my brilliant thoughts with the greater world, those were just my personal musings (as is this piece right here).
Don't get me wrong, I'd love to _be_ in a position where such long-term usefulness was expected.
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.
The big advantage of split keyboards is that a notebook fits nicely in-between the halves.
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.
In case you want to take a look at it, the author has posted a photo of a page of her notebook on her mastodon. https://tietz.social/@nicole/116048644600363842
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.
> under-appreciated is the degree to which writing itself drives strong memory formation, even if the notes themselves aren’t particularly good or detailed.
Exactly!
See https://news.ycombinator.com/item?id=46986532
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 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.
Same for me. I also make extensive use of adding links to anything relevant. Spent a bunch of time discussing something in a slack thread: link it. Read some documentation: link it. Had a chat with an llm in a chat window: link it. Writing notes about how a bunch of code works : link to the functions. For this last one I've registered a custom vim:// URL scheme on my system which lets me link to a symbol within a given file, and when clicked focuses the relevant tmux window and navigates the relevant vim instance (using named pipes) to the symbol, or opens a fresh one if not already open.
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!
How long before people realize that they too have limited context length and adopt:
- memory/yyyy-mm-dd.md
- MEMORY.md
- SOUL.md
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.
Is an engineering notebook a specific kind of notebook? Google has a lot of results for "engineering notebook" but they seem to be all expensive fancy notebooks that have thin gridded paper
From the article,
> I'm not talking about a specific kind of paper notebook.
So no. Just a regular old paper notebook. Any kind will do.
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
I do the same thing, but with a Markdown file which I add a section to every day in a roughly append-only fashion
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.
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.
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.
I use a physical notebook but not really an engeneering notebook as described here.
I 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.
Almost all my paper notes these days are write-only media.
The benefit is not the artifact itself, but the immediate act of formalizing the idea, emphasizing its importance, and being mindful/attentive to what's going on.
Right. I am not sure why people have a hard time understanding this.
You almost always remember more of what you have consciously written down by hand than by typing. You can write as little or as much as you see fit; the point is that the conscious involvement of "whole body and mind" in the act of writing enforces mental discipline, helps find inter-disciplinary patterns and in general, is an aid to thinking.
Here is an article on the brain areas involved in writing; Psychologically speaking: your Brain on Writing - https://uwaterloo.ca/writing-and-communication-centre/blog/p...
Finally, if you look at any of the great Scientists, almost all of them wrote prodigiously viz. Letters/Papers/Books/etc. I am quite convinced that this was one important factor in the development of their greatness.
My personal role model for writing is of course Edsger Dijkstra :-)
Surprised it’s not mentioned, but important for the sake of patents too
> Surprised it’s not mentioned, but important for the sake of patents too
Is this still true these days? I thought the US moved to first-to-file in the early 2010s.
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.
Interesting. I use a paper notebook to but it's the opposite of detailed. I use one when I have several ideas in my head and I need to get them out before I forget some, or when I need to figure something out that's a wee bit too complicated to keep all the bits and bobbles in my brain-RAM.
But I write down just enough to offload the memory to paper. They're literal notes. Just enough so that I can remember what I was on about earlier. But probably not detailed enough I could come back in a couple months and recollect the rest of the details. What's the point in that anyway? These are things I intend to act on. Once I commit them to code, then the code becomes the source of truth.
100% i've been using paper notebooks since I started coding
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
I do this but instead in a google doc. Even better because I can use LLM's to query it aftewards.
For me, this helps in getting clarity. I do it especially during meetings it helps me think criticallyb- talk just flows by otherwise.
Human journalctl. Probably a good habit to try. Especially with an LLM to search and aggregate it later.
[dead]
[dead]