Script for Notes

Posted on Tuesday, June 03, 2008

This past week I put together a writing tool that will likely strike you as insane, but may be helpful or interesting to a handful of people out there. For me, it’s helpful and in the off chance it’s helpful to someone else, I’ll put it up here.

Here it is, just a simple shell script that helps me organize notes as I’m working on my dissertation. Before I explain how it works, let me explain why I wrote it.

In the traditional workflow for academics, writing is usually the last step, after all the research is done. This is both for methodological reasons (you don’t always know what you need to write until you’re done) but also because of laziness: it’s easier to put off writing than to actually do it. However, for both reasons of personality as well as the type of research I do, this doesn’t work very well for me. To me, the writing process is part of doing the research. It helps me find holes in my research, clarify what exactly I’m doing, keeps me on track, etc.

The problem is that opening up a full paper, let alone a dissertation, to work on is a bit intimidating & distracting. So I tend to create & collect hundreds of disorganized notes. For some reason, if the writing lives in a different document, then that somehow eases the stress of writing for me. At the same time, I’ve learned that very often these “very rough first passes” that I jot down tend to look better than I think they will down the road. Of course, they need editing, but editing existing mediocre writing is easier than writing great stuff on demand from scratch.

Plus, I’ve found when you’re actually “in the moment,” reading a particular article or thinking through a particular conceptual problem, you’re better positioned to write about it well. The alternative—coming back to it when it’s officially “writing time”—can backfire because it’s just not as fresh in your mind anymore.

So here’s what I wanted:

  1. A system to help organize my notes a bit better.
  2. A workflow that was as quick & easy as possible. I know of full-blown desktop apps as well as web apps for organizing notes, but they all strike me as environments geared towards organizing, not writing, notes. Plus it's just slow & cumbersome to wait for a full-blown application or webpage to load.
  3. A system where the writing I put into these notes can easily be reused when it comes time to actually piece the final project together. In my case, I write everything in Vim using LaTeX, so ideally I can write my notes in Vim with its nice LaTeX syntax support.

So here’s how this script, here called ‘notes,’ works:

  1. To create a new note, I just type 'notes' at the command line. The script names the new note 'note#.tex' (where '#' is just a number that increments for each note file), and it adds the following text to the top of the file (here it's "note3.tex"): 
    % 3
% Mon Jun 2 16:11:33 CDT 2008
% TAGS:
    The script opens the file up in Vim, puts the cursor at line 3 automatically and from here I can type "A" and start adding tags to the file or just hit "o" and drop down one line and start typing the note. It automatically uses Vim's LaTeX syntax highlighting. When I'm done, it saves the file. (Unless I quit before adding anything, then it cancels the note.)
  2. It saves all the notes in a single directory, names them in a consistent way and then lets me search through them. To search through all of the notes for "foo," and then have all the matching notes displayed, run:
    notes -s foo
    To only search the "TAGS:" line instead of the whole note, just use -t instead of -s.

The advantages may not seem obvious to you, and they may be completely dependent on my own way of doing things, but here’s why this works for me: