The Hacker’s Notebook: A Mission Log For Every Project

While “writing it down” might seem like common sense, it wasn’t always the case. From the times of Ancient Greece, Plato tells a story of a worried Egyptian King, who, upon witnessing the invention of writing, remarks,

“If men learn this, it will implant forgetfulness in their souls; they will cease to exercise memory because they rely on that which is written, calling things to remembrance no longer from within themselves, but by means of external marks. [1]”

To some, the notebook was a dangerous device, a thief that would rob us of our memories [2]. Fortunately, these days, there’s plenty of evidence from our Psych texts that say we humans are pretty shabby at keeping the facts straight. In fact, each time we recall a memory, we change it! Here lies the beauty of the notebook. Have an idea for a new project? Why not log it somewhere for future reference? With diligence, the notebook can become our own personal hub for spurring on new project ideas.

The Project Log and You

Keeping a notebook takes time–time that cuts away from making the actual project. Nevertheless, I’m convinced that a little well-written forethought can be keep your eyes open to ideas that might otherwise be hidden when we’re focused on the details.

The Master Reference

It’s hard to resist the urge to leap in and start tackling the project head-on. A few resistors and op-amps on a breadboard later, and maybe we’re already halfway there. After all, why slow down drawing the circuit when you can just make it? Unfortunately, while we can get pretty far in one night, we can’t always finish. When that happens it’s far more difficult to restart from a crow’s nest of wires than it is from a master reference. Here lies the beauty of the notebook. When we compel ourselves to write down

every bit counts; some designs start on paper
every bit counts; some designs start on paper

an idea, we’re challenged to give an overarching depiction of what we’re trying to build with sufficient detail to construct it later. Once we’re actually building that 3D printer or breadboarding the circuit, we’ve got the dimensions or schematic we logged earlier to jump back into the same context. Fortunately, from block-diagrams, to circuit diagram symbols, to logic gates, previous engineers have created an entire vocabulary of symbols for communicating with each other. Why not use it to communicate with our future self?

The Multi-Body Solution

When we write down or type up our idea, we put deliberate efforts into entertaining it. Perhaps it’s another mechanism for robot locomotion. Maybe it’s a rough schematic for a switching power supply. Either way, to remember it later, we’ll need to give a sufficiently detailed description to recall it again when the time is ripe. If we can push ourselves to put this idea into our notebook, we can reap an interesting benefit. Now that it’s on paper or in text format, it can stand by itself.

When we look back on what we’ve written, perhaps, a day or two later, we can entertain it from an outside perspective. Reading over what we’ve written, we’re giving ourselves a second angle from which to look at the same idea–almost like getting another person’s opinion. And in one sense, it is. The notebook becomes a conversation with a “yester-you.” We give ourselves the ability to entertain many perspectives, each split across a different time period when they were written down.

Beyond Pulp-and-Paper: 21st Century Notebooks

It’s been a good 3000 years since the Mesopotamians started doodling cuneiform on clay tablets. Surely, we can do better! Fortunately, thanks to modern technology, we don’t need to keep scribbling like a caveman to keep our thoughts straight. These days, online build logs and digital photo albums have been helping us present ideas, but they can also help us generate them. I thought I’d shed some light on two modern-day tools that are tuned for the rough draft.

IPython Notebooks

ipython
Image Credit: IPython Developers List

Sometimes, we need to run a test-snippet of code to crunch some numbers. Perhaps we’re in the lab, running a quick experiment, or maybe we just need to double check our bit-math. IPython turns your web browser into an interactive Python terminal. Small snippets of code can be dropped into Mathematica-like “cells,” which can be run with a simple Shift+Enter. Being browser-based gives it the flexibility of running on any platform, and you can even run the notebook on a server remotely, allowing you full access to your notebooks anywhere you can find an internet connection.

IPython is the lab scientists modern day mission log. It renders LaTeX into beautiful mathematical equations, and it has all the tools and libraries available in Python. It’s cell-structure encourages small coherent snippets. With IPython, you can crunch numbers, plot data, and export html webpages, all from the comfort of your browser. For the curious, have a look at some other folks’ more polished lab manuals online, some of which are clean enough to be stand-alone works of technical beauty.

The IO: a connected build log

the_io
Hackaday.io; join the conversation as it happens

Paper may be able to give you the chance to revisit your own take on a project; but, sadly, others don’t become part of this feedback loop. Recording your thoughts and projects online gives you one edge from keeping a solo notebook: peer review. Keeping a notebook gives us the advantage of revisited a deeply thought-out topic with a fresh set of eyes. Publishing your thought process, however, actually gives us many fresh sets of eyes! If you’re getting started on a project and want to open it to the world, Hackaday.io is a fantastic place to get the project underway. No project need be complete to turn a few heads, request feedback, and get others to exchange a few pro-tips on your project underway.

Off the Mental Back-burner and On Paper

Whether we’re using a fully-fledged IPython interpreter, your anthology of builds on Hackaday.io, or scribblings on a few scraps of paper, we’re promoting spur-of-the-moment calculations. As the day goes by, we can take one or two of the many ideas that fly through our mind and catch them before they slip away. Most of these thoughts might not realize themselves into fully-fledged projects, but that’s OK. With our thoughts now on paper, in text files, or online, we’ve given these ideas the honest treatment they deserve of being entertained just by writing them down.

Surely, there are more pieces of technology that can help us save our thoughts. Google’s Keep, Github Gists, and DEVONthink are all fantastic examples of fresh pieces of software that help us log our thoughts. If you’ve got a particularly nifty way of taking notes, we’d love to hear them in the comments.

References:

[1] Plato on Writing. http://www.umich.edu/~lsarth/filecabinet/PlatoOnWriting.html

[2] Notebooks as memory aids: Precepts and practices in early modern England. Richard Yeo. Sage Publications 2008.

46 thoughts on “The Hacker’s Notebook: A Mission Log For Every Project

  1. I have lots of notebooks filled with schematics and drawings, descriptions and logic tables. I even take notes on “napkins” when I don’t have a notebook available and then later staple it into the appropriate project notebook.

    1. Whoa. Just goes to show you: The more things change, the more they stay the same.

      I was having a conversation the other day and we were debating whether or not easy access to information on things like wikipedia would make people more forgetful.

      1. The human mind has a limited capacity. That capacity is best used as an index to the library to get the necessary detail. Make no sense to waste that capacity on detail, when an index is al we need in a world overflowing with detailed content when needed, if ever needed.

  2. I actually have a hard-cover spiral-bound (Black-n-Red) notebook for project ideas, logs, and the like. I use fountain pens (some new, some vintage that I’ve rebuilt and restored) when I write, so the act of writing it down is as enjoyable as the project itself, and it helps me think, organize, and remember what I wrote. It also encourages me to write, since I love my pens.

    1. I second that writing project notes with a fountain pen helps encourage note-taking by making it more enjoyable and I also add that binding and pressing your own small notebooks helps as well. It’s also very simple.

    2. I put everything
      into an 8″ Windows tablet with
      the Wacom pen
      into One Note.
      Easy to find notes
      easy to sort and move
      always synchronized
      pen or keyboard
      Absolutely Love IT.
      ymmv.

    1. Until, the file format, data storage format, etc… is no longer readable on current hardware. Paper lasts essentially forever. Online scans as a backup and for indexing and searching; however, nothing electronic beats paper.

      Also, since when written in pen on proper lab notesbooks (with numbered pages) a physical notebook can serve as legal proof if you ever have your idea contested. Electronic versions are too susceptible to after the fact changes to be suitable for that purpose.

      1. The search features alone of are worth using electronic notebooks over paper. Plus the non-linear nature and ability to refine notes helps immensely. Any plots or images are easily copy and pasted to an entry. If I need a paper copy I can always print out what I need.

      2. Until you loose a notebook, I did in college. Harder to backup paper. My best solution was an HP CapShare, but the obex protocol was one of the thinks Microsoft borked in XP and I never got it working with Linux.

    1. I use an “At A Glance” Planner for quick notes. Otherwise, I carry a spiral notebook to work and back, it keeps my mater to-do list, meeting and phone call notes, and the occasional bright idea (or not).

      When I had nothing else but a phone, I called my voice mail and left a memo.

  3. For those who use Emacs editor and for those who dont, yet, I recommend org-mode. It is a notepad with a spreadsheet, a calendar and a todo list, supporting export to various formats (LaTeX, HTML etc.). It supports literate programming, GTD and git-annex attachments.. And the best of all: it is a plain text format.

    http://orgmode.org

  4. iPython changed its name to “Jupyter” (is that an oversimplification?) and development continues. One biggie is the addition of support for umpteen languages, including Erlang. Jupyter comes bundled in the Anaconda distribution of python if you want an easy installation. Just install it and then type “jupyter notebook”. Poof. It works.

    1. Pedantic addition:

      IPython is a python interpreter. IPython notebook, now called Jupyter, is a browser based interface to an IPython shell. Jupyter, as you mentioned, now supports a number of kernels for various programming environments, and also makes parallel programming fairly easy.

      Even without the notebook, IPython is a fantastic shell for python. Jupyter is a fantastic tool for development and note-taking.

  5. I found that next to keeping a hand-written journal using Microsoft OneNote was great for pasting in notes/images, etc for projects I worked on. I used that at work for keeping notes on many products and it worked out great. Easy to print out a hardcopy later for archiving.

    @dr_when

  6. No mention of Evernote? Really? Is it too popular for you guys?

    Mathematica actually has a good interface for taking notes and I did more then my fair share of homework assignments on it. If you have a Raspberry Pi it’s even free.

  7. Well, by comparison to others here, my note taking is a scattered mess.

    During initial research most note taking consists of saving/reading PDFs and printing a little.

    I use Javascript in a browser for calculated graphs when needed.

    All the way through I use little bits of paper about 3 American units square and they end up in the bin. For pinouts / clraft pin constraints I use A4 pieces of paper (about American “Letter”).

    Then when I am designing the PCB, my computer desk gets covered in so many bits and bobs that I measure and enter directly into CAD.

    Code is then done in an editor depending on what code it is.

    Most of the electronic info goes into a folder for the project.

    I have actually been looking for a project organizer or web site but they all have limitations like no keyword highlighting, no support for Javascript, poor image organisation, very limited support for types of file upload.

    To do it properly I should just use HTML. I am one of “those” people that learnt HTML Version 1 lol but I can stretch as far as XHTML 1.0 or HTML 4 dtd “Strict” by it’s other name.

    I probably would go so far just for me to read as I have the document navigation loosely fitting together in my head.

  8. I’ve kept a composition notebook of scrawled ideas for the past few years, it’s rough around the edges and nearly full these days. I like having paper copies of my ideas because something about physically sketching it out and writing down notes makes the idea stick more in my head. When I’m on the go, a small pocket notebook, PCB ruler and a smooth pen are an absolute MUST for me to carry

  9. I wish I had the time to stop and document something meaningfully. I do document but it is mostly chicken scratch on any nearby scrap of paper with no obvious connection or meaning. Evernote is like a mailbox slot I keep shoving written words and links into never to be seen again. I do worry that I am losing mental capacity or ability by off-loading information into digital devices, freeing my brain for new crap to be glossed over and filed away again.

  10. I use a graph paper project notebook. The brand used is not important, but the first page or two of mine is reserved for an index of the following pages. I review my ongoing projects nearly every day unless that day is consumed by other activities or just being focused up in a single project.
    Those pages are then either photographed with my phone camera or scanned into documents and organized with Trello.com in a project board. I then review all of my Trello boards nearly daily as well. On Trello, my projects can include sharing and collaboration with others and links to all of my documents, photographs, and outside links (such as from Evernote). I can also add the Trello cards to my calendar and set up reminders for due dates.
    The process itself is fluid and can change over time (such as if I find a better notebook), but for the most part it’s “how I work”. I find that it helps prioritize my time and helps eliminate procrastination and project clutter.
    I also carry a small sized notebook in my back pocket for when inspiration strikes, but those get transferred to my project notebook and Trello quickly.
    Seeing my various projects progress from paper notebook to digital format somehow helps with my creative and inspiration process. It brings it all together under “one roof” and is accessible nearly anywhere, even if I’ve left my paper notebook in the car, at home, or in my studio.

  11. When we compel ourselves to write down an idea, we’re challenged to give an overarching depiction of what we’re trying to build with sufficient detail to construct it later.

    Reminds me of this part of Painless Functional Specifications – Part 1: Why Bother?

    The most important function of a spec is to design the program. Even if you are working on code all by yourself, and you write a spec solely for your own benefit, the act of writing the spec — describing how the program works in minute detail — will force you to actually design the program.

  12. As a software developer, a maker, and a Mac user, I’ve used MacJournal for my project journals — both at work and at home — for years. Because I do most of my design/thinking at my Mac, for me an app like MacJournal — http://marinersoftware.com/products/macjournal/ — greatly increases my productivity. I can quickly capture and drag in screenshots and live URLs to supporting documentation, pictures of paper sketches shot on my phone, step-by-step notes on my progress, all into a new document page for each exploratory project “thread”. I can organize the results traditionally as an outline or cross-dimensionally using tags. I can create “smart filters” that surface just the *active* projects, or just the Arduino/RaspPi/whatever projects, etc (vs. projects on-hold in my backlog). And of course, being able to *search* across my entire “offline brain” is huge!

    Long ago I learned the importance of spending that extra bit of time — as my thinking on a project idea is evolving — to capture sufficient context about what I’m thinking and doing. Context is key. “I’ll remember this detail” has rarely worked for me. I force myself to go “up” in my thinking for a moment, to think as another person and what they would need to know to fully understand the ideas here and documentation I’m building (e.g. pointers to reference material that informed my design), to think about the assumptions I’m making but not expressing, about what I think is “obvious” right now which might not be so obvious later, especially to someone else, like my “future self”.

    A digital journal works for me. For my projects, the details/supplemental info live in MacJournal. The top-level “What am I working on now? What are the steps to moving project X to completion?” are expressed in an OmniFocus project. Knowing that I don’t need to remember key details (because it’s written down) and that I can switch projects/contexts quickly with minimal overhead (because it’s written down), helps keep me sane.

    1. +1 on the paper notebook. I use a composition book at home and a different one at work. It helps with context switching. Manually searching is a pain though. My handwriting is ugly enough that I am probably stuck with that method. Flat space on my lab bench is so scarce that a tablet would be about my only other choice over a notebook in my lap.

  13. Log books with non-removable pages are required by most engineering, medical, and lab professions.

    It provides legal proof of what was done, and is usually warehoused for several years after a project concludes.
    Often these are used to protect the authors from liability if an accident occurs due to an employer ignoring evidenced advice. Historically, they also provided forensic clues in the cases of unlucky scientists discovering something toxic/fatal.

    Indeed, paper is also harder to physically steal in large volumes by lamers.

  14. Since we’re throwing things out there… I prefer Jreepad. It’s an open source java-implementation knock-off of Treepad https://sourceforge.net/projects/jreepad

    It lets you create a tree-based directory of text. I like it because there is no support for text formatting, it’s ascii only (however it can export trees and sub-trees as text, HTML, and XML). Since it’s java it’s cross-platform which was one of my requirements.

  15. I agree proper notebook keeping is important, especially in the cleanroom of the silicon fab lab whers i work, as electronics are not permitted. Too bad clean room notebooks cost what they do…

  16. No one seems to have mentioned Livescribe pens yet….have had various ones for years; you get the paper notebook copy, and a backed up, SEARCHABLE electronic copy. Best solution I have found for my needs at least :-)

  17. I haven’t seen a post regarding the Rocketbook Notebook. It’s only 50 pages and you have to use the Pilot Frixion erasable pen. However, The companion app for your smartphone allows you to upload each page to the cloud. Dropbox, Evernote, Google Docs, Trello, ect. Then when the notebook is full, you set it inside of your microwave and heat it up. The ink from the Pilot Frixion pen completely disappears due to heat from the microwave. That leaves you with a completely empty notebook to start taking notes in once again.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.