This can be an incredibly powerful tool. It does so many things - it forces you to write down what you're doing. If you actually do that, it's just a great opportunity to think "Hey hang on, is this thing I'm doing actually solving the problem I have" and "Actually is this the most useful thing I could be doing" in an explicit way. Another thing that the author doesn't really mention but actually is really useful for some of us is to go back and read what you've done to (a) not feel like you've been wasting your time doing nothing, and (b) to realise where you were going wrong on this line of reasoning earlier.
Personally I think this is a really useful time to be revisiting the concept because this is how a lot AI tools work. They're language models so the way they get to complexity is through writing out plans step by step and running commands and then interpreting them, you can read your session with an AI agent like claude code as their engineering notebook.
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.
Engineering notebooks were required at my first job in the 1970s, for patent reasons. The notebook pages are numbered and it has a real sewn binding, making it harder to remove or insert a page without being noticed. We were required to date and sign each page and start a new page every day.
By the time I retired I think I was the only one at my company using one. I had to special order to get a proper one with the quad ruling, numbered pages, and sewn binding.
> 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
Anecdotally I've heard from my biochem circle of friends, that many institutions (at least in Germany) are still quite particular when it comes to lab notebooks. Especially ones that strongly monetize on patents, e.g. Frauenhofer. They usually also provide electronic lab notebooks which can either be used directly or into which you have to store copies of the original physical lab notebook.
I suspect that this may be due to different copyright mechanisms in different jurisdictions. e.g. in Germany employees have stronger protections that may allow them to still patent stuff developed in their free time, so companies might want to have a stronger papertrail to prove that outcomes tie back to something done during working hours.
As I understand it, Germany requires inventors to be paid royalties, so this may be a matter of ensuring that the actual inventors have been identified.
>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."
This puzzles me. If you are skipping a step in the procedure, aren't you also possibly going to skip writing a step down? And if you're not sure you wrote the exact right steps down, how are you going to use the notebook for that purpose?
What if you have to do several steps rather quickly? Say adding a particular chemical, then waiting for ten seconds and adding, another chemical? Do you have time to write it down?
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.
What I write down is usually a quite literal dump of my brain. I have a problem, and rather than keeping it in my head, I write it down, and force myself to continue writing about the topic to force myself trying to find solutions, rather than be obsessed with the question.
Example: "I need to solve problem A. Problem A can be formulated in this way. This way is similar to a project I did a few years ago, if I remember correctly I had done B and C. However B would not work in the current situation, but would it not though? The issue is that it clashes with component X and Y. What about C? Hmm maybe but I needed approval from Z." etc. All of these thoughts are written down, without filter.
Forcing me to write down has two effects. The first one, slow down my thoughts, because discarding idea B after only 0.1 second of consideration is not productive if you do not explicitly think about why it is a bad idea, and consider the bad idea anyways. The second one is that writing down (especially manual writing and not keyboard typing, for reasons I cannot explain) allows you to think more deeply about your ideas, to envision it in different ways, not only the first way that popped to your mind. I think that keyboard writing requires too much of my brainpower compared to handwriting.
Moreover, in these sessions, having the possibility to look back to a previous idea immediately is extremely useful, and cannot be attained if you use an erasable surface rather than a notebook.
I have to say though that I very rarely look back to what I wrote after the session took place, unless I need to get back to the exact same problem.
This is my process as well. I find it’s a good way for clearing out bad assumptions. Usually I’ve committed to my first idea, and writing it down gives me space to consider the alternatives. Usually I have a better idea that I haven’t worked out because the first one was lodged in my brain, and once that first idea is out on paper, I don’t have to worry about losing it anymore. The second idea is almost always better.
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.
I’m loving the Nomad. I’d buy it again if I lost or broke it.
The Remarkable Move finally pushed me over the edge to trying an epaper device. I bought it, used it, and sent it back[0]. In short, the hardware was great, but the software’s awful. Remember how iOS use to be skeuomorphic not just in appearance but in behavior, like you could only turn one Calendar page at a time because that’s that it’s like to navigate a paper calendar? Move’s software’s like that, with a thousand grating limitations because “that’s now notebooks work”. Can you add a dictionary to the ebook reader? No, because real books don’t have dictionaries! My gut instinct is that they don’t have the engineering resources to implement new features and that’s the excuse they give.
Supernote goes the opposite direction. Its software is leagues better for navigating within books. Like, circle some text on the page, tap an icon to make that a header, and now it appears in the doc’s table of contents. Tap it there and you’ll jump right to it. You can link to other docs. It’s closer to “a book… but better”.
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.
I use a daily log system. I just run this bash script to open my log for the day.
This opens the same file all day, so I can add stuff, and I know how to find old stuff, it's easy to grep, etc..
## create new log file for personal logging
vi ~/daily_logs/personal_logfile_$(date +%j_%m%d%y)
the "slowing down" part is the real value imo. i've noticed that the physical friction of writing (even just typing in a plain text file instead of a fancy tool) forces you to compress your thinking in a way that just staring at the problem doesn't.
there's a weird thing where the act of writing "i'm stuck because X" often makes the solution obvious before you finish the sentence. it's like rubber duck debugging but with yourself. i think that's what makes notebooks work for engineering specifically: the bottleneck usually isn't remembering what you did, it's noticing what you're actually thinking while you're doing it.
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.
- Notes about what I did, every so often. Or what I talked to someone about, what was decided.
- If I'm programming, I try to have a kind of plan for the next fifteen minutes / hour in a few sentences. "Going to refactor this now." "Updating the state here so it can hold this information." "Adding a component for this". Just so that I do think about what I'm going to do for a bit.
That sort of thing.
Apart from the to-do's the main point is to keep my focus, when I'm writing thoughts on paper I'm not on Hacker News. It doesn't matter all that much what the writing is, to me.
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.
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."
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.
These are the things I add in when adding in a new usecase to a codename:
- Expansion of the acceptance criteria into small steps.
- Any clarifications to what we are making
- Anything I don't understand yet so i can chase up someone about it later
- As I read through the code I write up possible refactoring opertunties. (I find this a lot better than adding todos as you can skim though the list closer to the end and address things that matter most first. Often the code that seems silly at first has a decent reason to be that way with the full context knowen)
All of this helps me pull the right threads without having to switch context throughout the day
> 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'm a software engineer, but I use it to write down hypotheses: the cause of a bug, how I'm guessing a system works, potential fixes for said bugs, what I think this piece of documentation means, etc
The practice of using a physical notebook, IMHO, is steadily fading into quaint retro irrelevance for most people in most roles.
I have seen absolutely meticulous lab notebooks before. Each page numbered and dated, cut-outs of graphs taped into the pages, that classy light-green grid-paper. Near flawless penmanship in black ink, with the rare correction crossed out, dated and initialed. Bibliographic references following a strict format in handwriting. Footnotes, FFS.
I've tried, in grad school, 20 years ago to get into the practice. Mine sucked. Non-stop, distracting corrections, maybe a dozen or more per page. Whole swathes of the notebook consisting of deep useless rabbit holes that started with a mis-conception or brain-fart, wasting space, making it a chore to even review what I was doing. I don't think of myself as particularly talented (maybe somewhat better than a fraud). But there are lots of folks like me and much smarter that have the same experience with paper notebooks.
I think really useful notebooks are something that is learned through practice, focus, and mentorship. But there are tools that are much easier to use these days. Notebook-based stuff like jupyter. I like quarto with ipynb myself (though it's not without occasionally infuriating problems).
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.
Looks like even Joe needed some time to adjust using an engineering notebook. He muses about how habits are difficult to change and that it might take him time to adjust to this notebook, and then goes on to wonder why this notebook was assigned and what kind of things he should document here.
This "it has to be handwritten" stuff is nonsense. Do that if you enjoy it, but also you should acknowledge the downsides to it.
I started keeping a work journal a few years ago and it has changed how I work for the better. It is just a text file.
The main value of it is that I can search it! When I'm figuring something out for the first time, and I have a lot of trail and error, I write down what I did. And then I might not touch that thing again for 6 months. When I come back to it, it is unlikely that I will remember what I did exactly but because it is written down and searchable I can quickly recover my old state.
I like this so much I also started a personal work journal for my home lab. It really is useful for me. But its primary value is that I can search it.
For me the advantage of using digital journalling is it's easier to switch between multiple threads. It means if I have 3 tasks to complete, I can switch tabs to the notes on the new task without thinking about the physical limitations of a notebook.
> This "it has to be handwritten" stuff is nonsense. Do that if you enjoy it, but also you should acknowledge the downsides to it.
From the submission:
"Should you use one?
Maybe! I can't answer that for you. "
There is a middle ground. Write on paper on the spot. Transcribe to digital form later. I've been doing it for many years. Painful, but now I just get an LLM to OCR my handwriting.
And oh, definitely - for me the brain works differently while typing vs handwriting.
It's not nonsense. At least it hasn't been for me. My memory retention shoots into the stratosphere when I write stuff (that I need to remember) down. Something about it being slower and actual effort needing to be expended to commit the information.
Handwriting is my primary notetaking route, but in situations where it isn't (typing is faster after all), I'll scribe what I typed into my reMarkable later. If the note I created was for work and I wrote a note by hand first, I'll type it into a Google Doc later and upload both versions (since they might differ slightly). I learned this as a study hack while I was in school 15+ years ago and it still works flawlessly for retention.
Handwriting everything has held me back sometimes, though. Ironically, insisting on handwriting everything is the reason why I didn't keep a daily journal for a long time. I started journaling in 2012 and stopped as work and life got busier. I picked it back up in 2021 with a mood tracking app to, well, track my mood and reactions to emotions and fairly quickly regretted not having just typed my journal entries.
I find there's an advantage to writing if I'm trying to memorize something. But if that isn't going to happen because I only did this configuration once and then never needed to reference it again for two years and now I need the exact commands I executed, can't beat a searchable txt file.
I handwrite notes because it commits it to memory and I don't have to search it later (most of the time). Important stuff goes in electronic notes, but 90% of things aren't that important.
Most of what I write in my journal I don't want to need to remember (that is why I am writing it down). I also don't know what will be important or not important later, so I want it all to be searchable.
Writing things by hand leads to better retention, but if you can't remember it...yeah you'll have a fun time finding it again if you have a nontrivial amount of notes and haven't spent a significant amount of time indexing them.
I stopped using my Remarkable because I couldn’t read my own writing on it. I have have no problem reading my writing when I write in a physical paper notebook (well, fewer problems). But the resolution either for capture or display on the remarkable makes my somewhat messy writing impossible to read.
So, it’s not only if you can’t remember it… you also have to be able to read it!
Yeah I was talking about Google Vision or similar. Though USPS has been doing handwriting recognition since the 80's. I don't it got very good until the late 90's though.
it sounds like the author is using an e-ink device for note-taking. i use an ipad app for a lot of hand-written notes and i'm consistently surprised at how well it can search my chicken-scratch.
my biggest issue with handwriting is it just takes so long that i end up leaving out important details. it's a shame because i do enjoy it.
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.
I've done this continually—initially writing in spiral notebooks—since I started writing computer games 40 years ago.
When at Apple, where it is probably widely known that there is an internal bug-tracking system called "Radar", a co-worker called my notebook style "John-dar" since I kept copious one-line to-do lists of issues still to resolve, tasks to tackle, etc. When all the circles next to each entry were filled in we could send the code to QA for integration testing.
To this day I keep a Field Notes book in my (largish) wallet to take notes as I think of things on the go. (Long, boring drives seem to be the best times when these ideas come.) I am in the habit of scanning the Field Notes digitally as they fill up and are replaced. (I only lost one when I lost my whole wallet on a 7-day Katy Trail bike ride. Still stings—why no one contacted me about it since email and phone # were in the Field Notes book.)
Sometimes it is fun to pick through older ideas, see ideas that I actually tackled and completed, other ideas that I am reminded of that may someday see the light of day…
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 keep a medium moleskine with the dots. Great for sketching UI designs or block diagrams. Dots are just enough guidance for technical drawing but not as distracting as lines.
So much more respectful in meetings to use pen and notebook than to use a digital writing medium. Not sure why but that’s the vibe I feel.
the underrated part of keeping any kind of work journal is that it forces you to articulate what you're actually trying to do before you do it. half the time when i write down "problem: X, approach: Y" i realize mid-sentence that Y doesn't make sense and i haven't actually understood X well enough.
i've been keeping a plain markdown file per project for about a year now. nothing fancy, just date-stamped entries with what i worked on, what broke, and what i decided and why. the "why" part is the most valuable: three months later when i'm staring at some code wondering why i did it that way, the answer is right there.
agree with the other comments that searchability matters more than handwriting. the notebook is romantic but i'll take grep over flipping through pages every time.
Did you one-shot this using an AI coding agent? If this was really just now created after reading this article and the comments, it's incredibly impressive.
Let's say.... 10 shot with Claude Code :) Initial app, then hand refined, Claude Code again...back and forth. Spend my morning doing it and it was fun. Very simple so far, want to clean it up and add more meaningful features.
EDIT: Also, turns out the in-browser Editor landscape got GOOD the last few years apparently. It's really just plug and play. I remember 5 years I tried to do this and it was painful.
In fact, I use several. I have a series of journals for graphics programming. One for proof kernels. A series for projects... if I'm working on a program that takes me longer than a few hours to realize I keep notes, plans, etc.
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.
I generally try to avoid adding external links as I found that those resources tend to get lost very fast.
Of course, this is not always feasible, but whenever I can try to copy over the contents into my notes.
I usually have a long running note per-project and whenever I need to context switch, I add a "Next Step: ..." line at the bottom of the doc. So I can jump right back in when I come back.
This is a powerful technique that has helped me a lot in the past as well, especially for those projects where I rarely progressed on (mostly private stuff, the work topics are more streamlined).
Nowdays in my private projects I often use a combination of the git commit messages and comments left in the code to indicate where to continue. Of course, this is not useful for work, either.
For work I like to use the ticket system and a separate text file and a paper notebook each to a slightly different effect.
The text file is the log what was done and is done per day grouped by ticket, typically ~10 lines for a day. The notebook contains meeting notes, design thoughts, general notes etc. and is very verbose (often six or mor pages per day, A4 paper) but sometimes helps to identify how/why/when a given decision was taken. The ticket contains what might also benefit others such as technical insights, meeting summaries (derived and summarized after the meeting from the paper notebook), summaries of important (design or product) decisions etc.
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'm talking about a practice of recording notes as you work on things, documenting what you're doing and why.
I've been using GitHub Issues threads for this for a few years now, in both public and private repos.
They work great for this. You can copy and paste code, images and references to code in repos to them, you can link them together, they offer useful API access, work on laptop and phone and are backed up by GitHub.
Obsidian with the (core) Daily Notes⁽¹⁾ plugin plus Jump-To-Date⁽²⁾ and Daily Note Navbar⁽³⁾ is a powerful combo for me.
Everything is still searchable (or can be fed into an LLM) since it’s all Markdown text files behind the scenes. (And I can type my thoughts much faster than I can write.)
Curious to know what you actually do with the notes, though. I've tried to get in the habit of keeping daily journals but it ends up being very much write once, read never. Maybe having some kind of fuzzy, semantic search or LLM would unlock their usefulness, but so far I don't find myself ever really using the things I write down.
For me it's mostly about being able to find stuff. For example, I save links (with some notes) that I've seen that day, and weeks/months later I'll remember "I read an article about $THING" or "I saw a repo that was similar to $THING" and I'll be able to find it.
Off the top of my head, I have used it to put links together — for example, a Stack Overflow description of some bug, the official documentation, and maybe copying in the exception or the error message.
Then I've sometimes done the same thing when I'm doing ops on a broken system.
Other times it's copying in a specific query or a link to a query in Application Insights.
Other times it's the ticket I was working on, a comment from a coworker, and maybe a few references to either tickets or files. Very rarely is this professional or looks nice. It's just that I need one place where I can put multiple things that fit together.
I find that retrieval does drop off very quickly. But that's just to say most of the value is front loaded. And we should not underestimate the value of being able to answer 'da fuck was I doing yesterday'. Context switching is expensive. But in many ways it is also unavoidable. If you context dump at the end of a workday, it's that much easier to return to it later.
The other thing I do is because the note system I use can I can drop in Hashtags. Yeah, I know. Not exactly HN friendly. What that means is I can find all the times I ran into the same issue, sort of weaving a meta thread through my work. It's really hard to explain, but it's one way of treating notes as not just segments of 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.
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!
This was definitely something I picked up from science education. Basically a technical journal.
These days I split between technical notes a write and store on the project git so others and the AI tools can read - eg architecture decision records, bug reports etc and then a separate personal linear time journal of what I’m doing / thinking/ task lists meeting notes etc, often with links to the project specific docs. Great for searching. What I miss from paper is ability to quickly sketch diagrams.
I don’t use a notebook and have done fine over the years - for those of you that are reading this and getting anxious you’re not doing your job the “right way”. I don’t have a particularly prodigious memory.
I’ve sometimes thought there’s a value to forgetting. If it matters I’ll learn it through repetition, like compression almost. It always seemed like reconstructing things from first principles saves brain space and allows for generalisation and creativity.
Absolutely agree, I do use notebooks but like you say I dont think I need to at all, for some reason I just have some natural drive to write things down (plus I like notebooks). But I've often had experiences of reading through old notebooks and finding that the things I care about in there I instantly remembered without having to read the page, and the things I'd forgotten about I didn't care about anymore.
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 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
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 :-)
Generally it is a good advise, I found similar things very useful for me.
I think emphasis on paper and one notebook is wrong here and likely will fail quite a bit of people who will try it. Also prescriptions like "They're very detailed" (i.e. notes) are IMO too rigid.
Start from wherever suit you, play, experiment and pay attention what works for you, adjust and iterate. Don't fixate on shiny concepts, i.e. "engineering notebook", and the "need" its records to be dated, etc.
Try something, let it lapse. See if you are worse without it, then adopt it back. If you don't see the difference, so be it.
The problem I always run into when I try something like this, is that I mostly (there are exceptions) use paper as a data processing medium (as opposed to a data recording medium). Most of what I do on paper is messy, half-baked, wrong, turns out to be a false start, whatever. Once all that is fixed, what is left gets tidied up into some sort of digital form, usually program code. I don’t want all that mess in the capital-N Notebook, but it is hard to know when to switch from backs of envelopes to the Notebook.
I suppose there might be a value in stopping right before the tidying-up stage (or perhaps right after it) and summarise the steps that led up to it (including abandoned approaches, and why) into some sort of document but that, for me, would be a digital file somewhere, not paper.
I feel I could write a long response to every comment in this thread as notekeeping is something I consider critical.
Knowing when to commit to “The capital-N Notebook” is something I’ve struggled with as well. What has been effective for me is to scribble daily on a marker/chalk/dry erase board and then transpose the final thought into “The Notebook” at the end of each day. This lets me format, err, mull, etc. and the final (sic clean) notebook still has enough granularity to retrace my thoughts in the med-to-long term.
> I don’t want all that mess in the capital-N Notebook, but it is hard to know when to switch from backs of envelopes to the Notebook.
On the contrary, I want and enjoy recording my failures, false starts in these notebooks. These are important lessons. A culmination of "what not to do"s, or "Lessons Learnt" in NASA parlance.
My engineering notebooks are my messy garages with working things on the workbench and not working things in a pile at the corner, recording how I think, what I think, and what works / what not.
The code is the distilled version of what's working, the "second" prototype, and the polished product.
Creation is messy, and there's no running away from that. Keeping the mess in its own place allows incubation of nice things and diving back into the same mess to find parts which works beautifully elsewhere.
I'm a simple man. I see a post about the reMarkable; I comment.
Buying this damn thing has been a life-changer.
I could never get on with physical notebooks, as I always lost them and searching for stuff was a chore.
It's an amazing companion for keeping track of everything I've written down, especially with the newest update that can _actually_ search handwritten content (instead of content that was typed, which previous versions were restricted to).
I especially appreciate the reMarkable team for sticking to their position of making the reMarkable a notetaking only device, even when it's inconvenient.
The reMarkable has been ESPECIALLY helpful for tracking my workouts. I've powerlifted for a long time and have experienced the rise and fall (or subscription-laden feature bloat and enshittification, more like) of The Apps™ (JEFIT, Strong, Hevy). More specifically, I like to leave my phone at home when I visit the gym, and none of these apps have provided a good experience on the Apple Watch.
Tracking my workouts on paper became increasingly attractive over the years; maintaining a small mountain of notebooks was not.
The reMarkable completely and elegantly solved this problem. I have a template I developed two years ago that works for my programs, and moving that data into a Google Sheet (whenever I get around to it) should be easy (though it's a lot of data, so it will take a long time).
For the last 5 years or so I've been keeping daily journals, which have migrated from one piece of software to another over time. Ultimately they all boil down to Markdown files named `YYYY/MM/DD.md`, the format has evolved into me just throwing a timestamp in as a header and then typing whatever thoughts I have.
These are useful for a couple of purposes, the first is simply getting thoughts out of my head and into a document. The other thing they've been good for is tracing back through what I've been doing - my job involves a lot of context switching, and it can be good (and sometimes also useful) to be able to scroll back through the last month and be reminded that I have in fact achieved something.
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.
Within software engineering circles, the idea of the engineering notebook was reintroduced in Hunt and Thomas' The Pragmatic Programming, where (Topic 22) they call it an "engineering daybook".
Personally, I've been using one form or another of journals and notebooks for over three decades. I did go through the "plain text is king" .txt phase, but, while search is useful, I always revert to a handwritten notebook.
I find that I have a sort of visual memory of the location of a note or scribble, and can sort of easily find my way back to it "in the lower-right side of the page near the end of the notebook".
Another meta-metric that's interesting to access and is lost when typing is the changing quality of my handwriting, and how it exhibits the underlying mental state.
The notebooks/journals started from standard local composition books (B5) to narrower 14x21-ish cheap hardcovers. There's also dates (manual), titles or topic tags (manual), page numbers (manual), cross-references with arrows (which do stand out amongst the handwriting, e.g. -> p. 20, or -> C/20 to xref back to notebook C when you're on notebook E), indexes (also manual), earmarked pages, and a physical bookmark string. I've also reverted back to pencil, which I find more "quiet" a medium - I've been using Faber Castell's sleek TK4600 since elementary school, and it was quite interesting to return to it a couple of decades later.
Plain text is still king nowadays, but it's also diagrammatic, and hyperlinked, the only difference being it is manual, and seems to assist immensely with the memory and personal internal coherence. I can write down a note to myself, working something out, and then return to it a couple of months later, cross-reference it and expand it, gradually reaching new understanding.
No need for slip card boxes when you have a running log of your thoughts and works that can be referenced and cross-referenced, nor is there a need to limit the length of your text because of the medium - write a bullet list if you want, checkbox it, or a 200-word vignette, or just let loose over a few pages, it's all good: a plastic medium for a plastic mind.
In all, for me journaling/notebooking is highly recommended. And for the younger folk who are keyboard-first, perhaps the deliberate slowness and scratchiness of this quaint medium will reveal a meditative quality.
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.
Never used one in over 15 years. I write a short post it only if I don't finish a certain task between days and it is really complex or maybe as a to-do list before leaving for holidays.
But I never felt the urgency to start a proper notebook. All the important decisions are documented in form of git commits for code or decision records for systems
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.
Tangentially, does anyone use a stamping device to put dates in their notebook? I am looking for something that sets the date and, preferably, the time automatically so that I have less friction keeping my notebook timestamped.
I increasingly use the rubber-ducking I do with an llm as a sort of engineering notebook or complement to one - I wish they had better search features.
ive been suggesting this to my teammates for awhile. i use mine to track long term goals, walk myself through my status on my in progress work items to prep for standup, and take any quick notes when i learn something new or need to remember something like a due date or a point of contact for something. pretty cool looking back through my old ones as well since I've been doing it since I was an intern (ive got like 5 years of notebooks now XD)
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.
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
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.
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 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
Personally I use loose leaf A4 pages, colored pens (massively useful!) and a padfolio with magnetic clip. When a bunch of notes are done, I'll staple them together and file them. I date stuff exactly or approximately or thematically group it. Then they go in boxed document folders (my context is insane, I work on mechanical/electrical/software/patents/random projects at the same time). Periodically, like changing countries, I scan stuff, digitize it, shred and purge.
Closed notebooks barely work because unless you're working on something highly sequential you wind up with 100 notebooks each of which have 5-15 pages used and are mostly wasted.
Occasionally, dated notes can be critical in IP litigation.
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.
This is all very familiar. As I work on one task, supporting tasks reveal themselves and I like to write it all down. There is something about writing it vs. typing it, too. Often, I will write notes like "Figure out how to do X,Y,Z" and then I wake up in the middle of the night and the solution is right there.
This can be an incredibly powerful tool. It does so many things - it forces you to write down what you're doing. If you actually do that, it's just a great opportunity to think "Hey hang on, is this thing I'm doing actually solving the problem I have" and "Actually is this the most useful thing I could be doing" in an explicit way. Another thing that the author doesn't really mention but actually is really useful for some of us is to go back and read what you've done to (a) not feel like you've been wasting your time doing nothing, and (b) to realise where you were going wrong on this line of reasoning earlier.
Personally I think this is a really useful time to be revisiting the concept because this is how a lot AI tools work. They're language models so the way they get to complexity is through writing out plans step by step and running commands and then interpreting them, you can read your session with an AI agent like claude code as their engineering notebook.
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.
Engineering notebooks were required at my first job in the 1970s, for patent reasons. The notebook pages are numbered and it has a real sewn binding, making it harder to remove or insert a page without being noticed. We were required to date and sign each page and start a new page every day.
By the time I retired I think I was the only one at my company using one. I had to special order to get a proper one with the quad ruling, numbered pages, and sewn binding.
> 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
Journalists should store their notebooks for 7 years.
Or put it in the shredder once the notes are not needed.
And only the confetti shredder is worth anything: https://www.youtube.com/watch?v=fVbFMyR-yWg
Anecdotally I've heard from my biochem circle of friends, that many institutions (at least in Germany) are still quite particular when it comes to lab notebooks. Especially ones that strongly monetize on patents, e.g. Frauenhofer. They usually also provide electronic lab notebooks which can either be used directly or into which you have to store copies of the original physical lab notebook.
I suspect that this may be due to different copyright mechanisms in different jurisdictions. e.g. in Germany employees have stronger protections that may allow them to still patent stuff developed in their free time, so companies might want to have a stronger papertrail to prove that outcomes tie back to something done during working hours.
Or Germany is just very particular about rules.
As I understand it, Germany requires inventors to be paid royalties, so this may be a matter of ensuring that the actual inventors have been identified.
(Note that this is why Jupyter and Wolfram use the word "notebook" for their interface format)
>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."
This puzzles me. If you are skipping a step in the procedure, aren't you also possibly going to skip writing a step down? And if you're not sure you wrote the exact right steps down, how are you going to use the notebook for that purpose?
What if you have to do several steps rather quickly? Say adding a particular chemical, then waiting for ten seconds and adding, another chemical? Do you have time to write it down?
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.
What I write down is usually a quite literal dump of my brain. I have a problem, and rather than keeping it in my head, I write it down, and force myself to continue writing about the topic to force myself trying to find solutions, rather than be obsessed with the question.
Example: "I need to solve problem A. Problem A can be formulated in this way. This way is similar to a project I did a few years ago, if I remember correctly I had done B and C. However B would not work in the current situation, but would it not though? The issue is that it clashes with component X and Y. What about C? Hmm maybe but I needed approval from Z." etc. All of these thoughts are written down, without filter.
Forcing me to write down has two effects. The first one, slow down my thoughts, because discarding idea B after only 0.1 second of consideration is not productive if you do not explicitly think about why it is a bad idea, and consider the bad idea anyways. The second one is that writing down (especially manual writing and not keyboard typing, for reasons I cannot explain) allows you to think more deeply about your ideas, to envision it in different ways, not only the first way that popped to your mind. I think that keyboard writing requires too much of my brainpower compared to handwriting.
Moreover, in these sessions, having the possibility to look back to a previous idea immediately is extremely useful, and cannot be attained if you use an erasable surface rather than a notebook.
I have to say though that I very rarely look back to what I wrote after the session took place, unless I need to get back to the exact same problem.
This is my process as well. I find it’s a good way for clearing out bad assumptions. Usually I’ve committed to my first idea, and writing it down gives me space to consider the alternatives. Usually I have a better idea that I haven’t worked out because the first one was lodged in my brain, and once that first idea is out on paper, I don’t have to worry about losing it anymore. The second idea is almost always better.
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.
What is the Nomad like? What were your concerns when selecting an epaper notebook? Which alternatives did you rule out and why?
Sorry, just long wanted to get one but the good ones are expensive and I don't want to experiment with that kind of money.
I’m loving the Nomad. I’d buy it again if I lost or broke it.
The Remarkable Move finally pushed me over the edge to trying an epaper device. I bought it, used it, and sent it back[0]. In short, the hardware was great, but the software’s awful. Remember how iOS use to be skeuomorphic not just in appearance but in behavior, like you could only turn one Calendar page at a time because that’s that it’s like to navigate a paper calendar? Move’s software’s like that, with a thousand grating limitations because “that’s now notebooks work”. Can you add a dictionary to the ebook reader? No, because real books don’t have dictionaries! My gut instinct is that they don’t have the engineering resources to implement new features and that’s the excuse they give.
Supernote goes the opposite direction. Its software is leagues better for navigating within books. Like, circle some text on the page, tap an icon to make that a header, and now it appears in the doc’s table of contents. Tap it there and you’ll jump right to it. You can link to other docs. It’s closer to “a book… but better”.
0: https://honeypot.net/2025/10/24/why-im-returning-the-remarka...
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.
I use a daily log system. I just run this bash script to open my log for the day. This opens the same file all day, so I can add stuff, and I know how to find old stuff, it's easy to grep, etc..
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.
the "slowing down" part is the real value imo. i've noticed that the physical friction of writing (even just typing in a plain text file instead of a fancy tool) forces you to compress your thinking in a way that just staring at the problem doesn't.
there's a weird thing where the act of writing "i'm stuck because X" often makes the solution obvious before you finish the sentence. it's like rubber duck debugging but with yourself. i think that's what makes notebooks work for engineering specifically: the bottleneck usually isn't remembering what you did, it's noticing what you're actually thinking while you're doing it.
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.
I write down:
- To-do items (with empty checkboxes)
- Notes about what I did, every so often. Or what I talked to someone about, what was decided.
- If I'm programming, I try to have a kind of plan for the next fifteen minutes / hour in a few sentences. "Going to refactor this now." "Updating the state here so it can hold this information." "Adding a component for this". Just so that I do think about what I'm going to do for a bit.
That sort of thing.
Apart from the to-do's the main point is to keep my focus, when I'm writing thoughts on paper I'm not on Hacker News. It doesn't matter all that much what the writing is, to me.
I always try to write what I did. Somehow the act of writing has a magical effect on my retention.
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.
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."
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.
These are the things I add in when adding in a new usecase to a codename:
- Expansion of the acceptance criteria into small steps.
- Any clarifications to what we are making
- Anything I don't understand yet so i can chase up someone about it later
- As I read through the code I write up possible refactoring opertunties. (I find this a lot better than adding todos as you can skim though the list closer to the end and address things that matter most first. Often the code that seems silly at first has a decent reason to be that way with the full context knowen)
All of this helps me pull the right threads without having to switch context throughout the day
What does it mean to add a usecase to a codename? Is this something you do frequently? And is it something you imagine others also do?
I assume that’s a typo for codebase
> 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.
I'm a software engineer, but I use it to write down hypotheses: the cause of a bug, how I'm guessing a system works, potential fixes for said bugs, what I think this piece of documentation means, etc
The practice of using a physical notebook, IMHO, is steadily fading into quaint retro irrelevance for most people in most roles.
I have seen absolutely meticulous lab notebooks before. Each page numbered and dated, cut-outs of graphs taped into the pages, that classy light-green grid-paper. Near flawless penmanship in black ink, with the rare correction crossed out, dated and initialed. Bibliographic references following a strict format in handwriting. Footnotes, FFS.
I've tried, in grad school, 20 years ago to get into the practice. Mine sucked. Non-stop, distracting corrections, maybe a dozen or more per page. Whole swathes of the notebook consisting of deep useless rabbit holes that started with a mis-conception or brain-fart, wasting space, making it a chore to even review what I was doing. I don't think of myself as particularly talented (maybe somewhat better than a fraud). But there are lots of folks like me and much smarter that have the same experience with paper notebooks.
I think really useful notebooks are something that is learned through practice, focus, and mentorship. But there are tools that are much easier to use these days. Notebook-based stuff like jupyter. I like quarto with ipynb myself (though it's not without occasionally infuriating problems).
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
Looks like even Joe needed some time to adjust using an engineering notebook. He muses about how habits are difficult to change and that it might take him time to adjust to this notebook, and then goes on to wonder why this notebook was assigned and what kind of things he should document here.
Nice!
Thanks for posting this find.
This "it has to be handwritten" stuff is nonsense. Do that if you enjoy it, but also you should acknowledge the downsides to it.
I started keeping a work journal a few years ago and it has changed how I work for the better. It is just a text file.
The main value of it is that I can search it! When I'm figuring something out for the first time, and I have a lot of trail and error, I write down what I did. And then I might not touch that thing again for 6 months. When I come back to it, it is unlikely that I will remember what I did exactly but because it is written down and searchable I can quickly recover my old state.
I like this so much I also started a personal work journal for my home lab. It really is useful for me. But its primary value is that I can search it.
For me the advantage of using digital journalling is it's easier to switch between multiple threads. It means if I have 3 tasks to complete, I can switch tabs to the notes on the new task without thinking about the physical limitations of a notebook.
> This "it has to be handwritten" stuff is nonsense. Do that if you enjoy it, but also you should acknowledge the downsides to it.
From the submission:
"Should you use one?
Maybe! I can't answer that for you. "
There is a middle ground. Write on paper on the spot. Transcribe to digital form later. I've been doing it for many years. Painful, but now I just get an LLM to OCR my handwriting.
And oh, definitely - for me the brain works differently while typing vs handwriting.
It's not nonsense. At least it hasn't been for me. My memory retention shoots into the stratosphere when I write stuff (that I need to remember) down. Something about it being slower and actual effort needing to be expended to commit the information.
Handwriting is my primary notetaking route, but in situations where it isn't (typing is faster after all), I'll scribe what I typed into my reMarkable later. If the note I created was for work and I wrote a note by hand first, I'll type it into a Google Doc later and upload both versions (since they might differ slightly). I learned this as a study hack while I was in school 15+ years ago and it still works flawlessly for retention.
Handwriting everything has held me back sometimes, though. Ironically, insisting on handwriting everything is the reason why I didn't keep a daily journal for a long time. I started journaling in 2012 and stopped as work and life got busier. I picked it back up in 2021 with a mood tracking app to, well, track my mood and reactions to emotions and fairly quickly regretted not having just typed my journal entries.
I find there's an advantage to writing if I'm trying to memorize something. But if that isn't going to happen because I only did this configuration once and then never needed to reference it again for two years and now I need the exact commands I executed, can't beat a searchable txt file.
I handwrite notes because it commits it to memory and I don't have to search it later (most of the time). Important stuff goes in electronic notes, but 90% of things aren't that important.
Most of what I write in my journal I don't want to need to remember (that is why I am writing it down). I also don't know what will be important or not important later, so I want it all to be searchable.
Writing things by hand leads to better retention, but if you can't remember it...yeah you'll have a fun time finding it again if you have a nontrivial amount of notes and haven't spent a significant amount of time indexing them.
I guess you could OCR them. Best of both worlds.
I stopped using my Remarkable because I couldn’t read my own writing on it. I have have no problem reading my writing when I write in a physical paper notebook (well, fewer problems). But the resolution either for capture or display on the remarkable makes my somewhat messy writing impossible to read.
So, it’s not only if you can’t remember it… you also have to be able to read it!
You can't OCR handwriting. There are some AIs that do claim handwriting recognition, but I've yet to find a single one that can read my notes.
I've only recently started using LLMs for OCR, and so far they've done a great job with my handwriting.
Yeah I was talking about Google Vision or similar. Though USPS has been doing handwriting recognition since the 80's. I don't it got very good until the late 90's though.
it sounds like the author is using an e-ink device for note-taking. i use an ipad app for a lot of hand-written notes and i'm consistently surprised at how well it can search my chicken-scratch.
my biggest issue with handwriting is it just takes so long that i end up leaving out important details. it's a shame because i do enjoy it.
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
About a year and a half ago we started writing end-of-day status reports at my job. They include what we did, and what we're going to do the next day.
I started really relying on the "what I'm going to do tomorrow" to remember where I start!
I've done this continually—initially writing in spiral notebooks—since I started writing computer games 40 years ago.
When at Apple, where it is probably widely known that there is an internal bug-tracking system called "Radar", a co-worker called my notebook style "John-dar" since I kept copious one-line to-do lists of issues still to resolve, tasks to tackle, etc. When all the circles next to each entry were filled in we could send the code to QA for integration testing.
To this day I keep a Field Notes book in my (largish) wallet to take notes as I think of things on the go. (Long, boring drives seem to be the best times when these ideas come.) I am in the habit of scanning the Field Notes digitally as they fill up and are replaced. (I only lost one when I lost my whole wallet on a 7-day Katy Trail bike ride. Still stings—why no one contacted me about it since email and phone # were in the Field Notes book.)
Sometimes it is fun to pick through older ideas, see ideas that I actually tackled and completed, other ideas that I am reminded of that may someday see the light of day…
Sounds like a great system! Would love to see photos if you have any!
What do you use to digitize your Field Notes? I was using EverNote but I’m looking for an alternative.
Just a flatbed scanner.
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 keep a medium moleskine with the dots. Great for sketching UI designs or block diagrams. Dots are just enough guidance for technical drawing but not as distracting as lines.
So much more respectful in meetings to use pen and notebook than to use a digital writing medium. Not sure why but that’s the vibe I feel.
the underrated part of keeping any kind of work journal is that it forces you to articulate what you're actually trying to do before you do it. half the time when i write down "problem: X, approach: Y" i realize mid-sentence that Y doesn't make sense and i haven't actually understood X well enough.
i've been keeping a plain markdown file per project for about a year now. nothing fancy, just date-stamped entries with what i worked on, what broke, and what i decided and why. the "why" part is the most valuable: three months later when i'm staring at some code wondering why i did it that way, the answer is right there.
agree with the other comments that searchability matters more than handwriting. the notebook is romantic but i'll take grep over flipping through pages every time.
Based on this thread, I decided to implement my best take on an online engineering notebook:
https://about.workledger.org/
All local first. Happy to get some contributors :)
Did you one-shot this using an AI coding agent? If this was really just now created after reading this article and the comments, it's incredibly impressive.
Let's say.... 10 shot with Claude Code :) Initial app, then hand refined, Claude Code again...back and forth. Spend my morning doing it and it was fun. Very simple so far, want to clean it up and add more meaningful features.
EDIT: Also, turns out the in-browser Editor landscape got GOOD the last few years apparently. It's really just plug and play. I remember 5 years I tried to do this and it was painful.
Crazy. Is it a library or ... ?
I use one too!
In fact, I use several. I have a series of journals for graphics programming. One for proof kernels. A series for projects... if I'm working on a program that takes me longer than a few hours to realize I keep notes, plans, etc.
Great practice!
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.
I generally try to avoid adding external links as I found that those resources tend to get lost very fast. Of course, this is not always feasible, but whenever I can try to copy over the contents into my notes.
I usually have a long running note per-project and whenever I need to context switch, I add a "Next Step: ..." line at the bottom of the doc. So I can jump right back in when I come back.
This is a powerful technique that has helped me a lot in the past as well, especially for those projects where I rarely progressed on (mostly private stuff, the work topics are more streamlined).
Nowdays in my private projects I often use a combination of the git commit messages and comments left in the code to indicate where to continue. Of course, this is not useful for work, either.
For work I like to use the ticket system and a separate text file and a paper notebook each to a slightly different effect.
The text file is the log what was done and is done per day grouped by ticket, typically ~10 lines for a day. The notebook contains meeting notes, design thoughts, general notes etc. and is very verbose (often six or mor pages per day, A4 paper) but sometimes helps to identify how/why/when a given decision was taken. The ticket contains what might also benefit others such as technical insights, meeting summaries (derived and summarized after the meeting from the paper notebook), summaries of important (design or product) decisions etc.
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'm talking about a practice of recording notes as you work on things, documenting what you're doing and why.
I've been using GitHub Issues threads for this for a few years now, in both public and private repos.
They work great for this. You can copy and paste code, images and references to code in repos to them, you can link them together, they offer useful API access, work on laptop and phone and are backed up by GitHub.
+1 on GitHub issues particularly as they now have:
- parent and child relationships
- the boolean search has gotten much better
- the CLI version integrates well with Claude etc
Obsidian with the (core) Daily Notes⁽¹⁾ plugin plus Jump-To-Date⁽²⁾ and Daily Note Navbar⁽³⁾ is a powerful combo for me.
Everything is still searchable (or can be fed into an LLM) since it’s all Markdown text files behind the scenes. (And I can type my thoughts much faster than I can write.)
⁽¹⁾ https://help.obsidian.md/plugins/daily-notes
⁽²⁾ https://github.com/TfTHacker/obsidian42-jump-to-date
⁽³⁾ https://github.com/karstenpedersen/obsidian-daily-note-navba...
Writing with a pen and paper is different from typing on a keyboard at. brain level.
I need to finish that research and write that blog post, apparently.
Curious to know what you actually do with the notes, though. I've tried to get in the habit of keeping daily journals but it ends up being very much write once, read never. Maybe having some kind of fuzzy, semantic search or LLM would unlock their usefulness, but so far I don't find myself ever really using the things I write down.
Same - they are too low quality for me to decode more than 8 hours afterwards.
For me it's mostly about being able to find stuff. For example, I save links (with some notes) that I've seen that day, and weeks/months later I'll remember "I read an article about $THING" or "I saw a repo that was similar to $THING" and I'll be able to find it.
Omnisearch is really good: https://publish.obsidian.md/omnisearch
I use a similar system at work.
Off the top of my head, I have used it to put links together — for example, a Stack Overflow description of some bug, the official documentation, and maybe copying in the exception or the error message.
Then I've sometimes done the same thing when I'm doing ops on a broken system.
Other times it's copying in a specific query or a link to a query in Application Insights.
Other times it's the ticket I was working on, a comment from a coworker, and maybe a few references to either tickets or files. Very rarely is this professional or looks nice. It's just that I need one place where I can put multiple things that fit together.
I find that retrieval does drop off very quickly. But that's just to say most of the value is front loaded. And we should not underestimate the value of being able to answer 'da fuck was I doing yesterday'. Context switching is expensive. But in many ways it is also unavoidable. If you context dump at the end of a workday, it's that much easier to return to it later.
The other thing I do is because the note system I use can I can drop in Hashtags. Yeah, I know. Not exactly HN friendly. What that means is I can find all the times I ran into the same issue, sort of weaving a meta thread through my work. It's really hard to explain, but it's one way of treating notes as not just segments of 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 used to carry a physical notebook, but now I just Brain Dump to a (now giant and growing) Notepad++ Text file.
Especially powerful if that text file is a Markdown file. The sidebar TOC view then becomes a powerful navigation aid.
Top of the file or end?
I used to do that but switched to Logseq and love it. Most people use obsidian.
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
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!
This was definitely something I picked up from science education. Basically a technical journal.
These days I split between technical notes a write and store on the project git so others and the AI tools can read - eg architecture decision records, bug reports etc and then a separate personal linear time journal of what I’m doing / thinking/ task lists meeting notes etc, often with links to the project specific docs. Great for searching. What I miss from paper is ability to quickly sketch diagrams.
I don’t use a notebook and have done fine over the years - for those of you that are reading this and getting anxious you’re not doing your job the “right way”. I don’t have a particularly prodigious memory.
I’ve sometimes thought there’s a value to forgetting. If it matters I’ll learn it through repetition, like compression almost. It always seemed like reconstructing things from first principles saves brain space and allows for generalisation and creativity.
Absolutely agree, I do use notebooks but like you say I dont think I need to at all, for some reason I just have some natural drive to write things down (plus I like notebooks). But I've often had experiences of reading through old notebooks and finding that the things I care about in there I instantly remembered without having to read the page, and the things I'd forgotten about I didn't care about anymore.
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.
The patreon plug for the image really tickled me.
Not because it's wrong per se but it's such an irrevant image of text.
Has the author used electronic notes then he wouldn't be paying the bandwidth to show me a photo of the screen of his eink device!
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 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 :-)
Generally it is a good advise, I found similar things very useful for me. I think emphasis on paper and one notebook is wrong here and likely will fail quite a bit of people who will try it. Also prescriptions like "They're very detailed" (i.e. notes) are IMO too rigid.
Start from wherever suit you, play, experiment and pay attention what works for you, adjust and iterate. Don't fixate on shiny concepts, i.e. "engineering notebook", and the "need" its records to be dated, etc. Try something, let it lapse. See if you are worse without it, then adopt it back. If you don't see the difference, so be it.
The problem I always run into when I try something like this, is that I mostly (there are exceptions) use paper as a data processing medium (as opposed to a data recording medium). Most of what I do on paper is messy, half-baked, wrong, turns out to be a false start, whatever. Once all that is fixed, what is left gets tidied up into some sort of digital form, usually program code. I don’t want all that mess in the capital-N Notebook, but it is hard to know when to switch from backs of envelopes to the Notebook.
I suppose there might be a value in stopping right before the tidying-up stage (or perhaps right after it) and summarise the steps that led up to it (including abandoned approaches, and why) into some sort of document but that, for me, would be a digital file somewhere, not paper.
I feel I could write a long response to every comment in this thread as notekeeping is something I consider critical. Knowing when to commit to “The capital-N Notebook” is something I’ve struggled with as well. What has been effective for me is to scribble daily on a marker/chalk/dry erase board and then transpose the final thought into “The Notebook” at the end of each day. This lets me format, err, mull, etc. and the final (sic clean) notebook still has enough granularity to retrace my thoughts in the med-to-long term.
> use paper as a data processing medium
I also do the same thing.
> I don’t want all that mess in the capital-N Notebook, but it is hard to know when to switch from backs of envelopes to the Notebook.
On the contrary, I want and enjoy recording my failures, false starts in these notebooks. These are important lessons. A culmination of "what not to do"s, or "Lessons Learnt" in NASA parlance.
My engineering notebooks are my messy garages with working things on the workbench and not working things in a pile at the corner, recording how I think, what I think, and what works / what not.
The code is the distilled version of what's working, the "second" prototype, and the polished product.
Creation is messy, and there's no running away from that. Keeping the mess in its own place allows incubation of nice things and diving back into the same mess to find parts which works beautifully elsewhere.
I prefer to embrace the suck and document it too.
I'm a simple man. I see a post about the reMarkable; I comment.
Buying this damn thing has been a life-changer.
I could never get on with physical notebooks, as I always lost them and searching for stuff was a chore.
It's an amazing companion for keeping track of everything I've written down, especially with the newest update that can _actually_ search handwritten content (instead of content that was typed, which previous versions were restricted to).
I especially appreciate the reMarkable team for sticking to their position of making the reMarkable a notetaking only device, even when it's inconvenient.
The reMarkable has been ESPECIALLY helpful for tracking my workouts. I've powerlifted for a long time and have experienced the rise and fall (or subscription-laden feature bloat and enshittification, more like) of The Apps™ (JEFIT, Strong, Hevy). More specifically, I like to leave my phone at home when I visit the gym, and none of these apps have provided a good experience on the Apple Watch.
Tracking my workouts on paper became increasingly attractive over the years; maintaining a small mountain of notebooks was not.
The reMarkable completely and elegantly solved this problem. I have a template I developed two years ago that works for my programs, and moving that data into a Google Sheet (whenever I get around to it) should be easy (though it's a lot of data, so it will take a long time).
For the last 5 years or so I've been keeping daily journals, which have migrated from one piece of software to another over time. Ultimately they all boil down to Markdown files named `YYYY/MM/DD.md`, the format has evolved into me just throwing a timestamp in as a header and then typing whatever thoughts I have.
These are useful for a couple of purposes, the first is simply getting thoughts out of my head and into a document. The other thing they've been good for is tracing back through what I've been doing - my job involves a lot of context switching, and it can be good (and sometimes also useful) to be able to scroll back through the last month and be reminded that I have in fact achieved something.
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.
Within software engineering circles, the idea of the engineering notebook was reintroduced in Hunt and Thomas' The Pragmatic Programming, where (Topic 22) they call it an "engineering daybook".
Personally, I've been using one form or another of journals and notebooks for over three decades. I did go through the "plain text is king" .txt phase, but, while search is useful, I always revert to a handwritten notebook.
I find that I have a sort of visual memory of the location of a note or scribble, and can sort of easily find my way back to it "in the lower-right side of the page near the end of the notebook".
Another meta-metric that's interesting to access and is lost when typing is the changing quality of my handwriting, and how it exhibits the underlying mental state.
The notebooks/journals started from standard local composition books (B5) to narrower 14x21-ish cheap hardcovers. There's also dates (manual), titles or topic tags (manual), page numbers (manual), cross-references with arrows (which do stand out amongst the handwriting, e.g. -> p. 20, or -> C/20 to xref back to notebook C when you're on notebook E), indexes (also manual), earmarked pages, and a physical bookmark string. I've also reverted back to pencil, which I find more "quiet" a medium - I've been using Faber Castell's sleek TK4600 since elementary school, and it was quite interesting to return to it a couple of decades later.
Plain text is still king nowadays, but it's also diagrammatic, and hyperlinked, the only difference being it is manual, and seems to assist immensely with the memory and personal internal coherence. I can write down a note to myself, working something out, and then return to it a couple of months later, cross-reference it and expand it, gradually reaching new understanding.
No need for slip card boxes when you have a running log of your thoughts and works that can be referenced and cross-referenced, nor is there a need to limit the length of your text because of the medium - write a bullet list if you want, checkbox it, or a 200-word vignette, or just let loose over a few pages, it's all good: a plastic medium for a plastic mind.
In all, for me journaling/notebooking is highly recommended. And for the younger folk who are keyboard-first, perhaps the deliberate slowness and scratchiness of this quaint medium will reveal a meditative quality.
I do the same thing, but with a Markdown file which I add a section to every day in a roughly append-only fashion
How long before people realize that they too have limited context length and adopt:
- memory/yyyy-mm-dd.md
- MEMORY.md
- SOUL.md
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.
Never used one in over 15 years. I write a short post it only if I don't finish a certain task between days and it is really complex or maybe as a to-do list before leaving for holidays.
But I never felt the urgency to start a proper notebook. All the important decisions are documented in form of git commits for code or decision records for systems
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.
Tangentially, does anyone use a stamping device to put dates in their notebook? I am looking for something that sets the date and, preferably, the time automatically so that I have less friction keeping my notebook timestamped.
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 increasingly use the rubber-ducking I do with an llm as a sort of engineering notebook or complement to one - I wish they had better search features.
ive been suggesting this to my teammates for awhile. i use mine to track long term goals, walk myself through my status on my in progress work items to prep for standup, and take any quick notes when i learn something new or need to remember something like a due date or a point of contact for something. pretty cool looking back through my old ones as well since I've been doing it since I was an intern (ive got like 5 years of notebooks now XD)
The big advantage of split keyboards is that a notebook fits nicely in-between the halves.
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.
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.
No. The author uses the term “engineering notebook” to make it sound different than what humans have already been doing for millennia.
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.
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 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
100% i've been using paper notebooks since I started coding
Personally I use loose leaf A4 pages, colored pens (massively useful!) and a padfolio with magnetic clip. When a bunch of notes are done, I'll staple them together and file them. I date stuff exactly or approximately or thematically group it. Then they go in boxed document folders (my context is insane, I work on mechanical/electrical/software/patents/random projects at the same time). Periodically, like changing countries, I scan stuff, digitize it, shred and purge.
Closed notebooks barely work because unless you're working on something highly sequential you wind up with 100 notebooks each of which have 5-15 pages used and are mostly wasted.
Occasionally, dated notes can be critical in IP litigation.
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.
This is all very familiar. As I work on one task, supporting tasks reveal themselves and I like to write it all down. There is something about writing it vs. typing it, too. Often, I will write notes like "Figure out how to do X,Y,Z" and then I wake up in the middle of the night and the solution is right there.
For me, this helps in getting clarity. I do it especially during meetings it helps me think criticallyb- talk just flows by otherwise.
I do this but instead in a google doc. Even better because I can use LLM's to query it aftewards.
Human journalctl. Probably a good habit to try. Especially with an LLM to search and aggregate it later.
surprised to hear others don't do this! obsidian also works well for daily notes
Since when do even bloggers try to get Patreon subscribers?