Using an 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?

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.

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

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.

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.

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'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…

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...

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.

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 use Obsidian to record decisions, plan every day and take detailed notes. Very handy for recalling the nitty gritty for future reference be it performance reviews, writing blogs or updating my resume.

I'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.

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 :)

Just wanted to flag the use of the little "jump back to where I was reading" links on the footnotes is a feature I'll be implementing and using on every footnote I ever write for the rest of my life now. Thank you!

I 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.

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.

In case you want to take a look at it, the author has posted a photo of a page of her notebook on her mastodon. https://tietz.social/@nicole/116048644600363842

I 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.

I used to carry a physical notebook, but now I just Brain Dump to a (now giant and growing) Notepad++ Text file.

> 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.

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 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.

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 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'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.

How long before people realize that they too have limited context length and adopt:

- memory/yyyy-mm-dd.md

- MEMORY.md

- SOUL.md

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

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.

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.

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.

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.

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.

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.

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.

Surprised it’s not mentioned, but important for the sake of patents too

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

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.

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.

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!