# notes on notes

This is a detailed, non-normative description of my note-taking habits. I have opinions, but this is not a prescription, a self-improvement text, or a guide to right living. Writing about personal productivity has a long history on the internet. Let’s stipulate at the outset that I’m not productive and won’t help you become that way either.

I’ve been writing things down for most of my life. Despite that, it wasn’t until my late 30s that I felt like I had a handle on deliberately taking notes. I don’t mean that I got good at it, just that I did it enough for patterns to emerge from the murk and feel useful.

Now I spend much of my time in my notes. I have, God help me, a system. The notes are a lever for understanding bigger things, part of the way I think about problems, and a space for doing other work. They’ve started to form a loose scaffold between a lifetime of other projects and preoccupations.

# table of contents

# overview

In taking notes, I’ve arrived at two broad and mutually reinforcing purposes:

  1. To think in writing, improving my memory and worked understanding.
  2. To store information for later reference, augmenting my memory with an external source of truth.

I take notes on paper, mostly in notebooks. I have opinions about notebooks and mostly write with fountain pens. I use some conventions for this, but in general I just write free-form journal-style entries by date. I use index cards and sticky notes for more ephemeral things.

I also take notes on computers, mostly in VimWiki, a personal wiki built on the Vim text editor. VimWiki offers a date-based diary as well as named wiki pages. I’ve extended this in various ways, and use a database called SQLite to collect metadata for navigation. I also use bookmarks, keep permanent command-line history, and try to leave README files where they’ll be helpful on my filesystem.

These tools are the core of a system addressable on two axes: Time and topic. I want it to be able to answer some questions: What is a thing? When did a thing happen? What things are related and how? How did they get the way they are? What else happened around the same time, or in the same context? Who was involved?

For navigating by subject matter I use tags extensively. I use the same mostly-flat namespace for wiki pages, tags on bookmarks and blog entries, and directory names.

For navigating by time, I rely on datestamps (both the ink and electronic kind), VimWiki’s diary features, and a simple logging system in VimWiki. I also use metadata like version control history, bookmark dates, and filesystem timestamps.

The rest of this document describes my approach in a fine-grained way, covers practices I find helpful, and notes some deficiencies. This isn’t a sophisticated system, but I’ve both stolen and developed some ideas for it. I conclude with an attempt at outlining those and giving pointers to sources.

# paper notes

Paper has many virtues. The salient ones might be summarized as follows: Availability, humility, spatiality, and durability.

Availability: Paper is nearly everywhere and can be had cheaply. It depends on an industrial civilization for this ubiquity, but it doesn’t depend on the power grid, batteries, or network access to be usable.

Humility: Paper contains no running code designed to harm the user, makes few demands, and can be transferred or destroyed at will. It’s open to modification, unencumbered by DRM, incapable of phoning home or being remotely modified to seek additional rent.

Spatiality: Paper has a physical place and a spatial relationship to other paper. It can be moved, held alongside other things, casually thumbed through. A page in a codex book or an index card in a stack comes with context and navigation. Something that’s still nearly impossible to recreate on a screen, where reading or writing a document is far too often like peering at some vast artifact through a narrow aperture.

Durability: No digital storage medium yet devised is as likely to still be readable in 20 years as the average paper book.

Finally, as important as anything else, paper is a physical pleasure to use.

# an aside: materials & cost

When I was a kid, my mom showed me how to use some basic plastic Sheaffer fountain pens she’d had in school. I still have those, and I’ve been interested in pens ever since. When I was in my early 20s, a long-distance crush sent me a pocket-sized Moleskine for Christmas, which started me on carrying good notebooks.

Writing implements and nice paper things are a hobby interest that I rely on directly for work, so I feel fine about spending some time and money on them. That said: No one needs a twenty dollar notebook, let alone a hundred dollar pen, to take useful notes. I think tools and materials that feel well-made are worth seeking out if you can swing it. There’s also much to be said for a Bic stick pen and a $0.50 spiral-bound notepad. Plenty of people feel that “nice” objects like the ones I mention below are too fancy to actually use, and get better results from the cheap and disposable.

As with cameras, I suspect that the best pen & notebook are the ones I have with me and actually use.

# notebooks: primary

At any given time, I have a single primary notebook. It usually goes in my bag or a pocket when leaving the house.

I look for these features in a notebook:

  • A5 (148 × 210 mm) or 8½ × 5″ in size
    • On trips where space is limited, I might switch to a pocket-sized A6 or 3½ × 5½″
  • Blank pages, ideally pre-numbered
  • Hardcover, thread bound, should lay flat
  • Decent quality paper, sufficient weight to take fountain pen ink without too much bleed-through, around 80 gsm or better is good
  • A durable back pocket
  • Ribbon bookmark(s)
  • Good archival properties

In 2022, a number of notebooks are available that more or less fit this profile. I used Moleskines for years, but these days the quality is uneven at best. Right now, I stockpile medium / A5 Leuchtturm 1917 books while keeping an eye out for the next alternative. I’ve recently tried similar makes from Apica, Ecosystem, Rhodia, Shinola, and WritersBlok. Of these, I’d use the Rhodia Webnotebook again.

I use blank pages because they feel, somehow, more free — more versatile for drawing and writing at different sizes. My handwriting, or at least my ability to write a straight line across a page, improved once I no longer relied on grids or lines for most things.

I’ve used much bigger notebooks, but they’re a pain to carry. Pocket-sized books are great for portability, but such a small page can feel cramped.

When I start a notebook, I write the starting date on the inside front cover, along with a mailing address in case of loss. I add a $20 bill to the back pocket to cover mailing costs (and because having a twenty in reserve for emergencies comes in handy). I leave several pages blank for adding entries to a table of contents (some notebooks have a table already printed for this).

The back pocket is important: I use it to collect small items like ticket stubs, receipts, and stickers. I keep a few loose pages of contact info and important dates, a sheet of stamps, a bookmark with pressed flowers on it that my Grandma made for me, and a spare envelope. These I transfer to the next notebook when switching, while leaving behind mementos specific to the timeframe covered by the notebook.

If there’s no builtin back pocket, I sometimes glue an envelope inside the back cover to serve the same purpose.

{PHOTO HERE}

I write in this notebook anywhere from a few times a month to a few times a day. Entries are by date. I start a fresh page for each day / entry, and headline the entry at the top of the page with the full date, including day of week and year, like “Sunday, April 10, 2022”. I underline that heading.

A journal entry starting Sunday, April 10, 2022

A primary notebook entry might contain anything from a grocery list to a draft of a blog post or letter. I write what I feel like writing, in whatever form I feel like writing it, and feel no compunction about “wasting space”. Most often, this means personal journaling, sketches, doodling, and creative work. I also jot notes on books I’m reading or stuff I’m watching on TV.

Once in a while I update the table of contents with page number, date, and one or more subject keywords for each entry.

When a notebook is full, I write its end date inside the front cover, and start a new notebook.

Missing features: I don’t yet have a great system for indexing into these books by date, but I think arranging them on shelves and labeling would take care of most of it. A topic index would be more work, but if I live long enough I may eventually start one.

# notebooks: scratch

In addition to the primary notebook / journal, I sometimes keep one or two separate “scratch” notebooks for working out technical ideas, taking ephemeral notes during the workday, making project drawings, trying out new pens, writing letters, etc.

For these purposes I’m not as picky about features. I lean towards things where removing a page is easy. This includes spiral or perfect (glue) bound notebooks, occasional legal pads, the various kinds of cheap freebies you sometimes get from conferences, and sketchbooks. Graph paper can be useful for technical projects and design sketches.

In the past I didn’t worry much about datestamping things, but over time I’ve found that temporal context is usually helpful.

# ephemera: scratch paper, index cards, post-its

For decades, my mom has cut junk mail and scrap paper down to size and kept a small magnetic box full of slips on the refrigerator, where they’re always handy for jotting notes. I’ve followed suit for much of my adult life.

I use small slips of paper for capturing brief observations and to-do items during the workday. These can be re-arranged on my desk, grouped, and copied to more permanent locations as needed, or even glued into a notebook.

If you’re looking for a prefab product, the Correct Joho Index Cards - 9.1 × 5.5 cm are an ideal size and fit nicely in a wallet or notebook pocket.

I keep a box of small blank slips on my desk and file them in a different box once to-do items are finished.

A cube of sticky notes is handy for attaching reminders to monitors or annotating other documents.

# writing implements & accessories

# fountain pens

Most of the time, I use a fountain pen. I’m always experimenting with this, but my current rotation is pretty stable.

Pilot Vanishing Point, fine nib:

Pilot Vanishing Point

This is by far the most expensive pen I own, and a favorite. It has a retractable nib deployed with a big clicky button, which is a revelation if you’re used to standard fountain pens with caps. I like this thing so much that I keep a spare stashed, new in box, in a drawer in my bedroom as a hedge against its inevitable loss or destruction.

TWSBI Diamond 580 Clear, medium nib:

TWSBI Diamond 580 Clear

This is an affordable, good looking pen that’s pleasant to write with and holds a great deal of ink without drying out. Unfortunately, the clear TWSBI pens have a couple of design flaws. The plastic tends to crack, and mechanically they’re more complex and finicky than I really like to deal with. I probably won’t get another when it breaks, but it’s nice to use until then.

Pilot Metropolitan, fine nib:

Pilot Metropolitan

This one is inexpensive and basic, well-made for what it is.

Innumerable doomed Parker 51 clones:

{PHOTO HERE}

I once owned a vintage Parker 51 in pristine working condition. I’ve since tried a series of knockoffs hoping to recapture that experience.

There are good candidates, but the closest approximation I’ve found to date sprang a leak after a few months of use. My quest for an ideal copy continues, but one of these days I’ll acquire a refurbished instance of the real deal.

The recent official Parker-branded 51 reissue is an overpriced cash grab. It’s neither a 51 in actual design nor is it a good pen on its own merits. (Parker is currently owned by Newell Rubbermaid, the same corporate parent that offshored Vise-Grip manufacture and owns Endicia, possibly the world’s worst shipping API. It’s hard not to feel that this explains some things.)

I try not to keep more than two pens inked at a given time, although enthusiasm sometimes gets the better of me. Two is a good number so I can pick one up immediately if the other runs out of ink mid-thought.

# ink

I want all the ink I use to be waterproof, light fast, and unlikely to eat holes in the paper. There are tradeoffs, however. Truly waterpoof pigment inks can be prone to clogging pens, and others just aren’t that pleasant to write with.

Mostly, I buy ink by the bottle, although I keep a couple boxes of Pilot Blue Black cartridges in my bag just in case.

Samples of Document Ink Black, Micron ink, and Pilot Black

Bottled ink I use regularly:

I used to buy Noodler’s Ink, and still have a few half-used bottles. There are some nice colors. But I find the ones I’ve used tend to bleed / feather more than I really want, and the manufacturer’s politics are unpleasant.

# other implements

I’ve gone through a lot of fineliner-style drawing markers in the last 20 years, especially when regularly traveling or commuting. I’m trying to use fewer, since they’re short-lived and result in a lot of plastic trash, but they do have a bunch of useful qualities: Archival, waterproof, light-fast pigment ink that lays down in a clean, dark, legible line.

Makes I’ve used heavily:

Of these, I’ve used the Sakuras the most — they’re widely available in the US — but I have a vague sense that the Faber-Castell products have been a more robust design and a better value for money.

I was given a Fisher Space Pen for Christmas a few years back, and it’s become a go-to for when I expect bad writing conditions. (Air travel, camping, bike rides in bad weather.) It’s just a completely unassuming classic ballpoint pen, except it happens to work every time.

I don’t use dry media much, but it’s nice to have wooden pencils handy for sketching and roughing out things like building plans. They’re also immune to the hazards of air travel and altitude changes, incapable of leaking or drying out, and free of moving parts.

I have accumulated countless free wooden pencils with corporate logos on them and certainly don’t need any more, but in 2021 a friend gifted me a Blackwing Pearl. After a year or so, I gave in and ordered a whole box of the things, which should extend the date I expect to run out of pencils until about half a century past when I expect to be dead myself. It’s just a nice pencil.

# electronic notes

Despite my fondness for paper, I’ve found that notes on the computer offer a lot of utility. They are, in no particular order:

  • Fast to enter / compose
  • Fast to traverse links between
  • Searchable
  • Scriptable: Subject to various automated tools
  • Editable, easily copyable, and translatable to other formats

I assume that cloud services, closed-source software, and very complex implementations will all betray their users eventually. This means I try to rely on human-readable text formats, stored locally.

In the past, I’ve used both small personal wikis and a simple local ~/notes folder with some free-form text files. This latter just contained ad hoc files about various topics for the first 5 or 6 years of its existence. (This, by the way, is a fine approach, and I encourage it as a place to start.)

# vimwiki

In early 2017, after a brief experiment with Emacs and Org mode, I adopted VimWiki and its diary features. Since then, it’s become a central part of my workflow. I currently have about 7000 pages in VimWiki, including around 2000 pages on individual topics and 5000 diary or log entries.

These days, a hotkey in my window manager opens and closes a window with a tmux process running a shell in my ~/notes directory. From there, I typically have vim open to some pages in ~/notes/vimwiki, usually including the diary page for the current day. I often also have a separate tmux buffer open for grepping files and the like. All of ~/notes is a git repo, committed daily and backed up to a local network drive.

I use VimWiki’s native syntax rather than Markdown. I’ve scripted some extra features for navigating between pages, logging events, generating links, templating, and running shell commands from inside pages.

I use a day’s diary page as a view of more fine-grained log entries about what’s going on and what I’m doing, a calendar summary, and a scratch page for general notes about the day. General long-term notes on a subject live on topic pages.

# diary pages

My use of the diary page has drifted from manually arranged free-form text to a scripted overview of more structured info.

Here’s an example, ~/notes/vimwiki/diary/2022-05-05.wiki:

= Thursday, May  5, 2022 =

%% exec-raw auto
%% nowrap

== log ==

<!-- exec-raw notes logs-by-date '2022-05-05' -->
  - 07:44:25 [[/log/2022-05-05-0744-25|One interview this morning]]
  - 07:50:11 [[/log/2022-05-05-0750-11|Renewing shutupcasey.com - USD 12.00]]
  - 09:11:46 [[/log/2022-05-05-0911-46|WMF All Staff meeting]]
  - 09:40:33 [[/log/2022-05-05-0940-33|Breakfast: A banana, cup of Pero]]
  - 13:30:52 [[/log/2022-05-05-1330-52|Sunny & puffball clouds; green after yesterday's rain]]
<!-- end -->

== calendar ==

{{{exec-raw cd ~/notes && calendar -t "20220505" -A 14 # calendar
May 08* Mother's Day (2nd Sunday of May)
May 15* WMF payday (approximate)
May 19  (friend) Ralph Grublemister birthday
}}}

== notes ==

A [[/wmf-train-deploy]] day, [[/wmf-train-deploy/1-39-wmf-10]] seems done this
morning.  Leaving for KS after work.

== TODO ==

  - [ ] [[/travel]]: pack for [[/kansas]]
    - [ ] suit
    - [ ] toothbrush
    - [ ] allergy meds
    - [ ] camera
    - [ ] recorder

The bare bones of this layout are generated from a template every time I load a new page in ~/notes/vimwiki/diary.

There’s a lot going on here, so I’ll break it down by section.

It starts with an unambiguous datestamp, followed by two directives that my Vim configuration picks up. %% exec-raw auto tells Vim to filter the page through a script which lets me embed shell commands and include their output. %% nowrap turns off text wrapping for this file.

= Thursday, May  5, 2022 =

%% exec-raw auto
%% nowrap

Next is a dynamically generated view of the log - the notes logs-by-date command here is run every time I open the diary page:

== log ==

<!-- exec-raw notes logs-by-date '2022-05-05' -->
  - 07:44:25 [[/log/2022-05-05-0744-25|One interview this morning]]
  - 07:50:11 [[/log/2022-05-05-0750-11|Renewing shutupcasey.com - USD 12.00]]
  - 09:11:46 [[/log/2022-05-05-0911-46|WMF All Staff meeting]]
  - 09:40:33 [[/log/2022-05-05-0940-33|Breakfast: A banana, cup of Pero]]
  - 13:30:52 [[/log/2022-05-05-1330-52|Sunny & puffball clouds; green after yesterday's rain]]
<!-- end -->

Log entries are brief, timestamped wiki pages with a useful title and links to relevant topics. These are where I record the events and ideas that happen during a given day. Much more about this later.

Next, a dynamic view of calendar events for the day:

== calendar ==

{{{exec-raw cd ~/notes && calendar -t "20220505" -A 14 # calendar
May 08* Mother's Day (2nd Sunday of May)
May 15* WMF payday (approximate)
May 19  (friend) Ralph Grublemister birthday
}}}

These are mostly holidays, important friend and family dates like birthdays and anniversaries, and a few known recurring events. This is provided by calendar(1), a classic Unix utility which displays events from a tab-separated text file.

Missing feature: This isn’t integrated at all with external calendars. It would be nice if it could be.

Finally, I sometimes write a few notes summarizing the day, and may have TODO items for the day:

== notes ==

A [[/wmf-train-deploy]] day, [[/wmf-train-deploy/1-39-wmf-10]] seems done this
morning.  Leaving for KS after work.

== TODO ==

  - [.] [[/travel]]: pack for [[/kansas]]
    - [ ] suit
    - [ ] toothbrush
    - [ ] allergy meds
    - [X] [[/canon-powershot-s95]]
    - [X] recorder

# the log

In March of 2020, I came up with a prototype for logging small pieces of tagged info in VimWiki. The design was informed by:

  • Discussion with Lars Wirzenius about his ikiwiki-based external brain and journal system
  • Reading about the Zettelkasten
  • Fediverse discussion of the Org mode agenda
  • The Wikimedia Server Admin Logs

The basic idea is that I press ,l, and a new file is generated in ~/notes/vimwiki/log/, with a filename based on the current date and time down to the second.

For example, here’s log/2022-05-05-1330-52.wiki:

%date 2022-05-05 13:30:52.463175502-06:00
%title Sunny & puffball clouds; green after yesterday's rain

[[/water]] [[/weather]] [[/apples]]

No appreciable damage from the small hail. Apple tree still has flowers.

[[/weather5280]] on rain:

https://www.weather5280.com/2022/05/04/thankful-for-water

Similarly to diary pages, the skeleton of a log entry - the date and title fields - is generated by a template when I open a new file in ~/notes/vimwiki/log/.

The top line after the title contains one or more links tagging this log entry to relevant topics. Everything after that is freeform wikitext; I often paste relevant context.

Although VimWiki has a separate concept of tagging and a specific syntax for that, I haven’t used those features much, because I don’t think of there as being much distinction between a link and a tag within personal wiki systems like this. (This follows ideas I developed while working on WalaWiki.) If a dated diary page or a log entry links to a topic, it’s effectively tagged with that topic, and vice versa.

If I’m looking at a topic page, I can press ,wl (I remember this as “what logs” or “wiki logs”) and get a window displaying all of the logs that link to it, in reverse chronological order.

{SCREENSHOT HERE}

This system has held up much longer than I expected. I’ll probably need to shard the log files into subdirectories by year or month at some stage.

Missing features:

  • I realized early on that I’d like to have my logs contain more rigorously structured/typed data than this allows, along with more automation in collecting it, for some classes of event. I still haven’t settled on a general pattern I’m very happy with for that problem.
  • I log plenty of things that are trivial and some that aren’t. When looking at a topic, it would be nice to have a way to signal that I only care about major events in the history.

# topic / tag pages

The topical entry for apples looks like this:

[[/food]] [[/trees]]

An fruit, from an tree.  We have an apple tree in the yard.  My parents
grow lots of apples.

= temperature / freezing of fruit =

Freezing point is allegedly 29°F.

[[https://ask2.extension.org/kb/faq.php?id=157126|How cold can it get before apples are harmed on the tree?]]

> The freezing point of apples is approximately 29º. However, the fruit will
> not freeze until it is at, or below, the freezing point for some time.

As with log entries, the first lines of topic pages usually contain links that I think of as tags.

Topic pages often link out to filesystem locations, version control repositories, web URLs, etc. While many are fairly brief, others are detailed overviews of a given topic, broken down into sections with a full table of contents.

The page for a given topic serves as a sort of hub - a place from which to access related topics, log entries, and bookmarks.

Missing features: I haven’t really settled on a unified way to handle references / citations / bibliographical data. I’d like a clean standard for modeling the things that I cite - books, papers, movies, poems, songs, etc., as well as web resources more easily modeled as bookmarked URLs. Right now I just make VimWiki pages based on titles, but this feels like it’s going to get messy.

# sidebar: why not org mode?

First, I was an Emacs user for a while in the late 1990s. This corresponded with the worst period of RSI pain I’ve ever experienced. I eventually had to stop using computers for a while. I’ve tried to re-engage with it here and there over the years, and it never fails to hurt my hands. Emacs is an amazing piece of software, and its input model is an elaborate torture device.

Second, after 20 years or so, Vim is etched into my brain on a level I can’t even really reason about. I’ve tried various emulations, including the very, very good one in Evil. Without fail, I find something that’s not quite right, and the frustration accumulates until I retreat to the warm embrace of the real thing. The last time it was something I could never quite articulate with the handling of line endings.

# pinboard

Pinboard is a subscription web app for bookmarking. You sign up for an account and install either a couple of bookmarklets or a browser extension, and then when you see something interesting on the web you click a button and (optionally) add a description and some tags.

I’ve had a Pinboard account since 2012, and have tended to use it increasingly over that time. I tag things heavily; if I have time I try to add a meaningful description, or paste a useful excerpt in the description field, bracketed by « and » (quotation marks not often used in English, which saves me from compulsively worrying about the proper nesting of single and double quote marks).

I’ve recently noticed that Pinboard supports use of the <blockquote> tag for that purpose, so if I want to differentiate a quote from my own commentary, I use that.

The rolling linkdump on p1k3 is based in part on my public links. It’s good software that I’m happy to support with dollars, and I tend to enjoy the author’s opinionating and other prose.

Still, this is a locus of several irritating questions for me: Is there a good reason not to have most of my web browsing history just logged locally, with archives? How much am I going to regret my reliance on a piece of closed-source software whose author might entirely lose interest or get hit by a bus?

I periodically export the data, but it’s reasonable to think that at some point I’ll need to do something more drastic about bookmarking.

# pinboard tools

My own hacky pinboard wrapper can ask the Pinboard API for recent bookmarks, bookmarks by tag, or a list of all tags. I’m sure there are better tools, but it was easy to write.

pinboard-to-sqlite is a small Python tool that lets me dump Pinboard bookmarks to a simple SQLite database with the following schema:

CREATE TABLE [posts] (
   [hash] TEXT PRIMARY KEY,
   [href] TEXT,
   [description] TEXT,
   [extended] TEXT,
   [meta] TEXT,
   [time] TEXT,
   [shared] INTEGER,
   [toread] INTEGER,
   [tags] TEXT
);

# my home directory

A long-lived personal computer filesystem is often messy, redundant, and full of weird corners. Mine is certainly no exception; elements of it have been accumulating since the mid-to-late 1990s, and I’ve made an effort to retain the same home directory for my last 5 or 6 computers.

For a while, I had the notion that I would move everything important into a ~/workspace/, and keep that directory synchronized between multiple machines. In practice this hasn’t really worked out, for various reasons too tedious to go into, but it did eventually lead me to a structure where things at the top of ~/workspace/ share names with tags / topic pages in VimWiki.

A few concrete examples:

  • ~/workspace/correspondence - documents written to mail; maps to the tag I use for logging letters & such
  • ~/workspace/p1k3 - the contents of p1k3.com; maps to the tag for stuff about that website
  • ~/workspace/photos - photo archives; maps to the tag for logging photo activity, talking about tools, etc.
  • ~/workspace/tickets - copies of event tickets; maps to the tag I use about same
  • ~/workspace/weather - weather data, screenshots of gnarly storms; maps to the tag for weather logs & such

I’m still experimenting with this, but it feels like a reasonable organizing principle that could eventually lead to some useful scripting.

# command line history

I keep a lot of command line history, right now by way of two mechanisms.

The first (and simplest) is that I tell zsh and bash to store as much history as possible in the same file:

# from .bashrc
export HISTCONTROL=ignoreboth
export HISTFILE=~/.histfile
export HISTSIZE=-1
export HISTFILESIZE=-1

# from .zshrc
export HISTFILE=~/.histfile
export HISTSIZE=15000
export SAVEHIST=9999999
setopt inc_append_history
setopt hist_ignore_space
setopt hist_ignore_dups

The second is a utility called commandlog that I sketched out in October of 2016. As of this writing, the current version hasn’t changed much. It just jams command history into an SQLite database, along with some context like working directory, hostname, and so forth. It’s definitely buggy as hell and does almost nothing. Still, I’d like to build on the idea.

I sometimes add human-readable comments to history for future searching and forensics work with a no-op script called comment. Eventually, I’d like to be able to add detailed notes to individual history entries, tag specific commands, and use tags to easily pull together scripts out of related sets of commands (or automatically build menus on a per directory or per project basis).

I’d like to treat command history as, at least:

  • a simple log (this one is obvious)
  • an act of documentation
  • an act of cumulative programming

The sheer amount of work that’s done on the command line is simultaneously a tragic waste of repetive motion and an untapped technical resource. I’d like to usefully formalize my habit of hitting Ctrl-R to search through history for the last time I dealt with a problem. This should be a healthy way to accumulate knowledge in a primary interface rather than a hacky fallback to bad habits.

# p1k3 & wrt

I’ve had a blog, or something sort of like one, since about 1997. Early in its life, I wrote a short Perl CGI script to display its contents.

display.pl eventually morphed into wrt, which is something close to a general-purpose static site generator, or at least a static blog engine. It uses a date-based tree of files which can contain raw HTML, Markdown, Textile, and a few other formats. It supports tagging of entries and generates aggregate indexes for tags and months / years.

There’s some overlap between wrt and VimWiki’s features. In practice I think of wrt as a tool for publication and composing / ordering longer documents like this one. Things that start on paper or in VimWiki often feed into blog entries.

I use mostly the same set of tags to categorize p1k3 entries that I use elsewhere.

# public technical notes

I sometimes publish notes on technical problems and work.

For a while I was keeping a separate technical logbook for this, but eventually it dawned on me that I already had a blog and I decided to merge those entries here, tagged as technical.

I like to try writing a detailed public explanation for significant changes I make to open source software projects. So, for example, if I do a project for Adafruit that isn’t otherwise described in a tutorial, release a new version of wrt, or write a new utility script for bpb-kit, I might write a blog post along the lines of these:

A preponderance of dull technical notes makes p1k3 drier and more boring than it would otherwise be for any general audience. That’s kind of depressing for someone who would like to publish things like poems and photos, but it’s also largely by design. As I keep writing, I’m reluctant to publish personal material into a network environment as culturally and technically fucked up as the present-day internet. As it stands, it’s probably dangerous enough to provide a text corpus for future machine learning models to use in convincingly imitating me. (More about that under security.)

# templates & fragments

{to come}

# metadata

{to come}

# general techniques

There are some helpful ideas that span both analog and electronic media.

# datestamps

I’ve mentioned dates a lot. In general, it’s important that human readable dates be “complete” - including the year and day of week. This way the reader can tell the temporal context of an entry at a glance, which is particularly useful on paper.

I bought a self-inking date stamp in 2019 and have started using it on more paper items and at the top of notebook pages.

It’s important that machine readable dates be easy to cross reference, sort, and parse.

VimWiki uses ISO 8601 dates for diary entries. That is: zero-padded YYYY-MM-DD. So ~/notes/vimwiki/diary/2019-03-03.wiki is the diary file for March 3, 2019. This is a good habit to follow: It’s easy to sort or manipulate with common tools, fixed-width, and unambiguous.

p1k3 entries are stored in a directory hierarchy like YYYY/[M]M/[D]D, so ~/p1k3/archives/2019/3/3 contains the entry for March 3, 2019. Months and days aren’t zero-padded, so sorting can get a bit awkward, but I’ve more or less been happy with this scheme for many years. It can be constraining, but simple rules like “blog entries are stored by day in a rigid directory hierarchy” are useful scaffolding which can free an author to experiment in other ways.

# quoting

Along with excerpts when bookmarking, I quote from relevant chat traffic, e-mail, and documentation in my electronic notes, sometimes editing for concision or clarity.

Quotes make grepping easier, and people have often put a lot of thought into communicating an idea by the time it gets to my notes. Summarizing and re-stating are good tools for improving your own memory and understanding of a topic, so I do plenty of that as well.

I’ve learned it’s never safe to assume I’m going to be able to find some piece of information again just because we have search engines. If it’s important enough, I consider making a local copy.

When working on paper, copying out material longhand is much more labor-intensive, but can be a useful aid to memory.

As an important exception to this entire practice, I don’t quote stuff that would embarrass, incriminate, or expose other people. I try to remain mindful that my notes, however locked down, could compromise privileged communications.

# TODOs and checklists

In August of 2014, I wrote about my checklist habits:

I keep a lot of notes on paper. For stuff I want to do, I make lists with little square checkboxes next to individual items. If I get something done, I put a checkbox in. If I move the item to another list, I draw a little circle in the box. If I decide it doesn’t need done any more, I draw a line through the whole list item. At work I keep these under my keyboard on the biggest piece of printer paper I can find. Elsewhere I’ve usually got a notebook going. Every once in a while I go through the last couple sheets of paper and the most recent notebook, and make sure everything gets marked done, not-needed, or moved.

…and described an approach to doing the same inside a notes.txt.

I still do this, but more of my TODO items live in VimWiki pages now. I use a script to find unfinished TODOs across wiki pages.

# security

Despite my best intentions, this section is quite prescriptive.

This is a document about the utility of writing things down, but there’s a tension here. The first thing is that if you’re really worried about security, don’t write shit down.

(As a corollary, logging things like command line history has potential downsides. You need to be aware of the potential for accidentally storing credentials or dangerous metadata in plaintext if you’re doing that kind of thing.)

The last 30 years have shown us that in the wrong hands data is a toxin, a vulnerability, and a fatal temptation. The wrong hands might be those of corporation, state, programmer, ideologue, troll, stalker, and political agitator. They might also be yours.

If your job exposes you to the personally identifiable information of customers or users of software, your organization might have a policy about it. If not, or if your organization’s policy isn’t strict, here’s a substitute policy: Don’t copy that stuff into your notes.

If you are doing anything illegal where you live, you shouldn’t write about it, period. Not on paper, not in a text file, not on the internet. The same thinking applies if you are doing anything technically legal but likely to get you killed, beaten, fired, divorced, publicly humiliated, etc.

I try to be realistic about my threat model: Yes, American governance is deteriorating, but for right now I live in a stable region with low crime and relatively little violence. I’m extremely un-famous and politically uninteresting. I’m a straight white male with above-average income in a prosperous part of the central US. This all means that my threat model involves:

  • My network attack surface: Targeted or opportunistic attacks on my employers and, to a lesser extent, my personal systems.
  • The loss or theft of devices or notebooks.
  • Doxing by the shithead internet.
  • The ambient surveillance, malware, and fraud we’re all subject to.
  • Routine interactions with border agencies and the TSA.
  • Occasional, if escalating, natural disasters.

It specifically does not involve:

  • The focused attention of:
    • State-level actors / three-letter agencies.
    • High-level law enforcement.
    • Muckraking journalism, political opposition research, etc.
  • An ideological / cultural conflict in which my beliefs, identity, or relationships are likely to get me jailed or murdered.
  • The long-term collapse of civil society.

Given these priors, I keep the following rules in mind with regards to note materials:

  • Don’t write credentials (or account details, if I can help it) on paper, especially paper that’s going to travel. Exceptions exist for keeping passphrases or 2-factor auth backup codes on paper in a safe location.
  • Encrypt all drives, including laptops and mobile devices.
  • Automatically lock my screens.
  • Use a password manager with data separate from the body of my notes.
  • Don’t trust cloud services.
  • Don’t travel with anything I’d rather not have compromised, especially across national borders.

# ideas

Why take notes?

  • Writing is a way to think.
  • Writing is a way to store things for future reference.
  • Logging actions, events, and ideas is useful.
  • Tracking sources enables future research and thinking.

What medium is best for note taking?

  • Paper is good, actually.
  • It’s ok to combine paper and digital notes. Some redundancy is healthy.
  • Plain text is as future proof as it gets on computers.
  • Lightweight markup adds useful features to text files, but can be a trap.

How should a collection of notes be structured?

  • Tree structures are hard to think about.
  • Hierarchy has its place, but flat namespaces are a powerful default.
  • Structure emerges from flat collections with links, tags, and indexing.
  • Linking and tagging can be collapsed into the same action.
  • Notes should be findable by time and topic.
  • Bookmarks are just a note about a source: Useful if you can find them the same way.

What’s the best system?

  • One the note taker will use.
  • One the note taker controls. Business, programmers, and the cloud can’t be trusted.
  • The stupidest thing that could possibly work often works longer than expected.
  • One default notebook at a time makes life easier. A default channel for electronic notes does the same.

What’s the correct attitude towards systems?

  • Systems are ridiculous, and will keep spawning as long as written culture lasts.
  • It’s worth studying systems, to a point.
  • Benefits of study: The chance to steal.
  • Risks of study: Notions of self-improvement, full-blown methodology cults.
  • Fear of missing out can lead to good experiments, but is a poor guide to practice in general.

# sources

{work in progress}

My public bookmarks on notes and some related topics can be found on Pinboard under (at least) the following tags:

notes notebooks paper pens writing logging zettelkasten hypertext

The rest of this section is an attempt to sketch out some sources in very roughly the order I encountered them. It necessarily elides and distorts. Like everyone else, I am an unreliable narrator, and I didn’t start taking notes soon enough to be sure about many of these.

A number of themes run throughout. I’ve marked each source with one or more characters to indicate these:

  • 📔 Paper
  • 🗃️ Index cards, slip boxes / Zettelkasten, related ideas
  • 🔗 Hypertext
  • 🌐 The web
  • ⌨️ Text editors
  • ✍️ The act of writing
  • 🏷️ Tags and tagging
  • 🗓️ Time and dates, the temporal axis

# 1990s

  • 🗓️📔✍️ Family calendars
    • My grandma, Lois Bearnes, kept these calendars where she’d briefly note the day’s events. She used a kind that seems hard to find on the internet now, but used to be a common co-op / bank / feed company giveaway in the rural midwest. They had a cardboard back with a spiral binding for the pages. I think each page was probably a week, with a few lines for each day. They functioned as a kind of key to family memory. If you wanted to know when something happened, you asked Grandma and she’d have written it down.
    • Similarly: My mom, Deb Bearnes, has kept a big paper calendar for the current month hanging on the refrigerator for decades now. She tapes together 4 pieces of printer paper and draws a grid. It serves as a reminder of upcoming events and a place to log things as they happen.
  • 📔 Science class logbooks
    • Ed Brogie insisted we keep logbooks, in those black & white covered composition books. There was a handout about Bloom’s taxonomy that was supposed to structure the entries. It always felt arbitrary and straight-jackety. All the same, I must have taken something away from it, even if just an exposure to the habits of observation, record keeping, and making predictions to test against later findings.
  • 🔗 HyperCard
    • Sharon Van Cleave let me hide out in her computer lab reading the HyperCard book and making stacks while I was ditching Social Studies. HyperCard is a hard thing to explain. It came with every Mac for a while in the late 1980s. Bill Atkinson talks about being inspired to write it during an acid trip. HyperCard stacks are documents based on the metaphor of a stack of cards, where the user can place arbitrary graphical elements, UI widgets, and text. Objects can link to other cards or trigger actions in a built-in scripting language. It all adds up to something in-between a paint program, a database, and an IDE. It was a hugely influential precursor to the web and the wiki.

# 2000–2010

  • 🔗🌐 C2 / WikiWikiWeb / Ward’s Wiki: The first wiki. A place for talking about programming, but more importantly a laboratory for the wiki itself as an idea.

  • 🔗 Vannevar Bush:

  • 🔗 Ted Nelson: computer lib / dream machines

  • 🔗🌐🗃️ Brent Newhall:

    • I’m reasonably sure Brent turned me on to C2 and wikis generally.
    • In the era of wikis implemented as simple CGI Perl scripts, Brent wrote one called WalaWiki. I ran an instance on p1k3.com from about 2004 to 2014, maintained my own fork starting somewhere around 2007, and for a time folded it into the code that became wrt. Along the way, I formed ideas about how hypertext systems ought to fit together and the kinds of notes I’d like to take.

  • ✍️ Paul Graham:

    • Many years on, I have come to think that Paul Graham is full of shit, and the why of that is probably at least partly visible in these pieces. All the same, I have to give him credit for planting the idea of writing as a way of thinking. And for encouraging people to read Montaigne.
    • The Age of the Essay
    • How to Write Usefully

  • ⌨️🔗 Shane at the Coffee House in Lincoln, NE: At least I think his name was Shane. One of the first people I ever met in person who had truly gone all-in on an editor. (Emacs, of course.) In 2004, I wrote: “Last night I talked for a while with a guy who’s turned his text editor into a central organizing principle. He has a huge stack of text files named after different terms and a set of Emacs macros for navigating them. Sort of a homebrewed personal wiki. Or like one of those people you read about with a physical filing system where there’s an index card or a manila folder or a knotted string for everything, only you can jump around in it without getting papercuts. He’s pushing 10000 entries.”

  • 🗃️🔗 Taking Note, by Manfred Kuehn:

# 2010–present

tags: topics/notes, topics/pens, topics/technical, topics/vim, topics/vimwiki, topics/writing, topics/wrt

p1k3 / notes-on-notes