My Disposable Notebooks

For about a decade I maintain a certain habit: taking notes both at work and when studying/learning. The studies part is obvious, but at work it helps me a lot when I have to repeat something not trivial or infrequently done, or somebody mentions a topic that I remember I wrote about. As I just finished filling a notebook, thought maybe could be somewhat interesting to share my (basic and non-spectacular) method.

Physical notebooks

Apart from the "digital notes", to which I'll come later on this post, at 2017 I started to use simple Moleskine or alike paper notebooks. My writing is terrible but this way I keep a thin thread of "usage" and not totally forget how to write. I also recall reading or hearing somewhere (I think at this course) that writing notes while learning helps to "learn better", that it boosts your retention, probably because of the explicit effort of repeating the things you write down.

My main idea is that the notebooks are disposable, so it's fine if I write in a hurry some gibberish (that I later need to decrypt), or improvise, or jump between different topics and link with some crappy arrows and add later notes of notes of notes. If something is important I underline it and then move it "to a permanent storage" (a document, a post-it, whatever). And as soon as one notebook is filled up, I destroy it and start a new one.

It helps me a lot to unload things I have in mind, as if I did a kind of quick brain dump to reuse my (not so huge) brain RAM for other more relevant topics. It is like in meditation when you're told not to ignore distracting thoughts, but instead to "acknowledge them" and then go back to the meditation.

Digital notes

Since 2009, at most jobs I've also kept a "digital notes" document. Sometimes it's more of a cheatsheet of how-tos, commands and technical ceremonies you need to perform (e.g. deploying to staging requires A and B, then go to C then summon D and wait for a solar eclipse). Other times, is a collection of self-reminders, known pain-points, or mere indexes of relevant-to-me-at-least documentation. And they always contain a bit of my brain-dumps regarding some component internals or service tweaks that I considered relevant at some point... and then forgot to ever remove from the doc.

I initially just used it myself, but then the collaboration magic happened: I started sharing it with some colleagues, and they enjoyed it (and a few times, somebody suggested an improvement here and there). Then, when mentoring new hires I decided to share the doc with them, typically with a disclaimer like "it won't make much sense now, but in the future you'll probably find something inside that will help you". And they also found it useful.

From the feedback I've people seem to like it, so I keep doing these chaotic-but-somewhat-useful docs, now both for myself and for others that come after me. When I've changed jobs I ensured it had a new owner before my last day.

Existing documentation

While I don't find useful at corporate level maintaining wikis and the like, mostly because information disperses too much and gets obsolete incredibly fast, what I try to always do since some time also are two actions, no matter if the company is big or small:

Even if not required to do so, I write a small informal GDoc technical spec of any non-trivial project. While I try to keep relevant info in the ticketing system, Github issue or whenever the task at hand originates, I like to keep notes, alternatives and research outcomes, small how-tos that could come handy later when building the project's final documentation, etcetera. I usually simply have a GDrive shared folder (either the whole company, with "all tech" or simply with my manager and peers) where I put all of the tech specs and data fixtures.

I am a firmly believer that a concise but useful README.md per repository should be mandatory. I've seen and felt the pain of struggling with a simple "how the heck do I install this service?", versus a "I simply followed the readme and in 5 minutes it was all up and running", and it's quite the difference. Sometimes it's hard to strike a balance between too short and too long, but a minimal "pack" of intro + setup + running + testing is a great initial version.

Closing remark

It might look as extra work, but both when using the physical and/or the digital forms of the notebooks, I always try to add relevant information back to where it should belong. e.g. if a service's README has no testing instructions, adding some basic steps; If there's a "how to deploy your service to a specific staging instance" but the servers list is incomplete or obsolete, just updating it. It doesn't takes much time and that's the best way to help everyone.

My Disposable Notebooks published @ . Author: