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
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?
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.
I still find lots of value in keeping notes though! And sometimes miss it when I didn't keep notes.
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.
- 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.
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.
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.
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.
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 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)
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 vastly prefer just making a working skeleton and filling that with actual code as I progress.
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.
This has a couple benefits. First, you always get better work if you go through more than one draft. Second, the idea of something being in the "permanent" notebook forever can cause me to freeze up a bit, not wanting to "mess it up". Having a place where I can "stage" or draft my entries helps with this.
> I'm not talking about a specific kind of paper notebook.
So no. Just a regular old paper notebook. Any kind will do.
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.
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.
- memory/yyyy-mm-dd.md
- MEMORY.md
- SOUL.md
My workspace is just a markdown file, with dates and work-in-progress (scripts, bug investigations, design notes, task lists...), by date (reversed), rolled up to month files. If something (non-code) bears remembering, it's normalized and published to others, or put into my own topic space (leaving the WIP notes).
The key feature is global search over all such files. I can find any activity and any topic in seconds, with a search-bar overview of all places where I addressed some subject. (As a result I tend to create unique names.)
As a discipline, speaking directly and constantly to future self does help establish more methodical approaches, reinforces context awareness (and avoid ratholes); I restart even small projects where I left off, and scale the number of projects I try. Somehow the act of writing provides a reflective time/instant boundary (think: clocks in a functional universe) that orients the work in time/relevance to avoid wasting time on things that matter less.
I 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.
But i went back to them maybe 5 times in all those years. And the effort of writing actually distracts me more than the effortless action of typing. Plus the search and backup functions.
Even in high school in the early 90s I typed up all my class notes because the act of transcribing my written scratch to typed notes cemented it in my memory — i remember the sensation of recalling something for a test by air typing.
I guess with this history, its just how Ive trained myself so I carry laptop every where I go and type on that, but I al jealous of some of the well crafted and illustrated notes of some peers — especially the ones with multicolor pens for differentiation.
I 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.
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.
Is this still true these days? I thought the US moved to first-to-file in the early 2010s.