Using Org Mode to keep a process journal

I (re)started keeping a journal in Org Mode – chronologically-ordered snippets on what I’m doing, how I’m doing things, and how I’m thinking of improving. I’d mentioned the idea previously on my blog. In this post, I want to share the workflow and configuration that makes it easier for me to log entries.

When I’m on my personal computer, I use Org Mode’s org-capture command to quickly capture notes. I’ve bound org-capture to C-c r, a remnant from the way I still think of it as related to the even older org-remember and remember functions. Anyway, org-capture allows you to define several org-capture-templates, and it will display these templates in a menu so that you can choose from them when creating your note.

Here’s the template I’ve been using for my captures:

(setq org-capture-templates
      '(;; other entries
        ("j" "Journal entry" plain
         (file+datetree+prompt "~/personal/journal.org")
         "%K - %a\n%i\n%?\n")
        ;; other entries
        ))

This stores a link to the currently-clocked task and to whatever context I was looking at when I started the journal entry. It also copies the active region (if any), then positions my cursor after that text. Unlike the default template, this template does not include an Org heading. That way, I don’t have to think of a headline, and I can also just clear the buffer and close the window without adding lots of half-filled-in entries in my journal.

The file+datetree+prompt keyword means that the entries will be stored in ~/personal/journal.org in an outline corresponding to the year, month, and day that I specify. This makes it easy to write an entry for today or for any particular date. For example, I often find myself adding more notes for the previous day (-1) because of something I remembered.

I’m thinking of making Fridays my day for reviewing what I’ve learned and writing up more notes. With the date-tree structure, it’s easy to review my notes by day and look for little things to harvest.

If I know I want to revisit something, I can also add a TODO right in the journal entries using the regular Org syntax or as a keyword that I can search for. If it’s a separate heading (ex: *** TODO Take over the world), I can use org-refile to move it to its proper project.

When I want to flesh out those rough notes into a blog post, I can copy the entry to my blog post outline, fill in the details, and then use org2blog/wp-post-subtree to post it to WordPress. Alternatively, I might edit my rough notes in-place to make them ready to post, and then post them directly from that buffer (possibly changing the heading).

Since I’m not always on my personal computer, I need to be able to pull in notes from elsewhere. I can add quick notes to Evernote on my phone. So far, I’ve been okay with copying snippets manually. If I find that I’m creating lots of notes, though, I might look into reusing the code that I have for building my weekly review list from Evernote notes.

Time-wise, I find that spending 15-30 minutes at the end of the day helps me braindump the key points. If I take little writing breaks throughout the day, that helps me capture more details (especially in terms of development or technical troubleshooting). Re-reading my notes is part of my regular weekly review process, so it’s pretty quick (plus a little more time if I’m writing longer blog posts).

That’s how Org Mode helps me keep a process journal. It’s great to be able to quickly write notes in the same thing you use to do everything else, and to tweak your workflow. Whee!

Thinking about word counts and chunks

I was talking to Frank Chen about blogging, and he mentioned that he’s experimenting with word count goals. That made me realize that I don’t pay much attention to word count when I write, and that I tend to write shorter posts. I think in terms of chunks of ideas. I write each post so that it covers one idea, either something I want to share or something I want to learn. Sometimes I cover a little more ground, if I can chunk the sub-ideas enough to hold them in my brain at the same time. Sketches help me a lot when it comes to developing thoughts further.

I rarely write larger posts that bring lots of things together. I guess it’s because I tend to write about:

  • things I’ve just learned: publishing small chunks helps me get my notes out faster
  • things I’m figuring out: nibbling away at questions helps me make sense of them
  • answers to specific questions: small chunks and clear titles makes it easier for me to find things and share links later

What are some examples of longer posts and resources I’ve worked on?

  • There’s How to Read Lisp and Tweak Emacs, which I published as a four-part weekly series and also as a single file.
  • There’s the No Excuses Guide to Blogging, which I published as a PDF/EPUB/MOBI. I linked the source blog posts into a series so that people coming across the posts in the archives can still navigate between them.
  • I post presentations like The Shy Connector as slides and a full blog post. That said, I usually try to keep my presentations to about 10-15 minutes anyway, so the resulting posts are not enormous.
  • Interviews or videos with transcripts can get really long because I talk quickly. For example, this Emacs Chat with John Wiegley is pretty long. I’ve experimented with breaking transcripts up into logical segments, but keeping the entire transcript together seems to make more sense to me.

What would it be like to experiment with longer posts that cover more ground? Based on the blogs I like reading, I think it might mean writing more thorough guides like the ones on Mastering Emacs – things that people would bookmark and refer to a few times.

Organized guides help beginners a lot because they don’t get lost trying to figure out the next step. They can keep scrolling down. On the flip side, it might take a bit more work to make long guides friendlier for intermediate and advanced users: a table of contents, links to alternative paths or related content, closer and more coherent discussion…

Hmm. I feel a little odd about drafting a long resource (takes time to write and takes time to read), and deep-linking into part of a blog post can be a little difficult.

I think I like working with short chunks that I can link to or assemble into different pieces. Maybe I’ll spend a little more time planning outlines and series of related posts so that I can link posts together and fill in the gaps. For now, I’ll leave the ultimate-guide-writing to other people who are better at linear organization (or to future Sacha when she writes books).

Onward to better writing and sharing!

Weekly review: Week ending November 21, 2014

Wow, did I ever get a lot of sleep last week. Fortunately, I’ve been able to turn over all my responsibilities, and I’ve given myself permission to take it easy. I’m rarely under the weather like this, and it’s an interesting learning opportunity for dealing with variable energy and short attention spans. The blog has been coasting thanks to the posts that I wrote a week or two ago, but since I still do manage to learn something here and there, I’ll see how many posts I can squeeze in to remind me of stuff that I may want to think about later or that other people might find useful. =)

I still managed to do a little bit of consulting here and there, thanks to the wonders of working from home. =) This week, I discovered that recursive queries in PostgreSQL (WITH RECURSIVE) are actually a pretty fast way of traversing an organizational chart described as an adjacency list. I also wireframed a prototype so that one of the other developers can work on it, but she’ll probably need a little more help before she’s ready to take that on. I’m getting better at asking people to do things instead of giving into the temptation to have all the fun myself!

We’ll keep things loose. I’ll try to take notes along the way. =)

Blog posts

Link round-up

Focus areas and time review

  • Business (14.4h – 8%)
    • E1: Plan how I can work from home for the next few weeks
    • Read AngularJS documentation
    • Review bookkeeper feedback for tax return
    • Earn: E1: 1-2 days of consulting
    • Earn (6.8h – 46% of Business)
    • Build (7.6h – 53% of Business)
      • Drawing (2.3h)
      • Delegation (0.0h)
      • Packaging (0.0h)
      • Paperwork (2.4h)
    • Connect (0.0h – 0% of Business)
  • Relationships (20.2h – 12%)
    • Work on E
    • Follow up on insurance paperwork
    • Work on E
  • Discretionary – Productive (2.6h – 1%)
    • Emacs (0.0h – 0% of all)
    • Writing (0.0h)
  • Discretionary – Play (15.6h – 9%)
  • Personal routines (26.8h – 15%)
  • Unpaid work (4.8h – 2%)
  • Sleep (83.6h – 50% – average of 11.9 per day)

Keeping a process journal

I post a lot of notes on my blog, and I keep more snippets in my personal files so that I can learn from them and turn them into blog posts later. There’s something still missing here, though, something I can tweak. Reading Louise DeSalvo’s The Art of Slow Writing (2014), I recognized part of what was missing in her description of process journals. Here’s a relevant excerpt:

p82. In Steinbeck’s April 9, 1951, entry, written as he composed East of Eden, he evaluates his desk’s new surface, determines how to keep his pencil drafts from smudging, figures when it’s best to do his laundry, plans his week’s work, determines to try to write somewhat more, assesses his energy level, discusses his fear of interruptions derailing his work, pledges maintaining his focus to complete the work by managing his work in his journal.

… Here we see Steinbeck deliberately managing his work before he begins the labor of writing. He evaluates his tools–his desk and pencils–shapes his day, sketches the new scene, deals with his emotions, summarizes and evaluates his progress, and figures how to move his work forward. And Steinbeck engaged in this process each day.

(Oh! I love writers Have Thought About Stuff. It’s like the way programmers also tend to apply tools and systems to more than just programming… Come to think of it, I wonder how geeks of other persuasions end up applying their geekdoms to the rest of life!)

Anyway: a place to clear your thoughts, a deliberate reflection on processes and practices, and perhaps a way to browse through those entries in chronological order or based on context… My blog is a little like that, but there’s so much more stuff than I publish on it and it will continue to be like that if I insist on keeping to my mostly-one-post-a-day limit and scheduling things in advance.

I’ve been keeping a small journal–just a few keywords per day, scribbled into a paper notebook shortly before going to bed–for the past three months. It’s amazing how that’s enough to help me get back to those days, remembering more details than I could without them.

Org Mode for Emacs has built-in support for quickly capturing notes and organizing them in an outline by date. I think I’ll use that for at least quick memories, since those make sense in a timeline, and then I’ll keep the larger notes in a topic-focused outline. Technically, I’m using a computer, so I should be able to organize things both ways: using tags and links to connect items by topic, and using Org’s log view to view things by date.

It would be good to start with this kind of deliberate, constant improvement in a few areas of my life:

  • Web development: I’d like to learn more about design, and also developing better code
  • Writing: I can pay more attention to the questions I formulate and how I explore them
  • Cooking: Hmm, more notes on how we make the recipes and what the cooking process is like?

If I make Fridays the days I focus on harvesting my notes from the previous week and plan some ideas for the next one, that would fit in nicely with reviewing this process journal and seeing what I can build on the next week. (I’m still going to post random snippets during the week, probably… =) )

Beginner web dev tip: Use Inspect Element to learn more about HTML and CSS on a page

One of the neat things about learning web development is that the Web is full of examples you can learn from. You can use your browser’s View Page Source or View Source command (available from the right-click menu in Google Chrome, Mozilla Firefox, or Internet Explorer). An even better way to explore, though, is to use the Inspect Element action from the right-click menu in those browsers. If you right-click on the item you want to learn more about, you’ll be able to see the HTML and the current CSS applied to the page.

I use Google Chrome most of the time, so I’ll show you Inspect Element screen in that browser. Here we’re looking at the button on CSS-Tricks.com:

2014-11-10 15_37_06-CSS-Tricks.png

You’ll see the HTML on the left side and the CSS on the right. You can check or uncheck different CSS rules, and you can double-click on things to edit them. Check out the right-click menus for even more options.

Sometimes you may need to click on a different element in order to see the CSS rules that are relevant to what you’re curious about. As you hover over different elements, you’ll see them highlighted on the page.

If you click on the Console tab, you can experiment with Javascript too. If you want to view both the inspect element information and the Javascript console at the same time, click on the icon that looks like a > on the right side. This is particularly handy if you have a large screen.

Hope that helps!

First steps towards Javascript testing

I know, I know, it’s about time I got the hang of this. Better late than never, right? =) Anyway, I spent some time going through tutorials for QUnit and Jasmine. For QUnit, I followed this Smashing Magazine tutorial on Javascript unit testing. I modified the code a little bit to add the Z timezone to the test data, since my tests initially didn’t pass.

test.html

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Refactored date examples</title>
    <link rel="stylesheet" href="http://code.jquery.com/qunit/qunit-1.15.0.css" />
    <script src="http://code.jquery.com/qunit/qunit-1.15.0.js"></script>
    <script src="prettydate.js"></script>
    <script>
     test("prettydate.format", function() {
       function date(then, expected) {
         equal(prettyDate.format('2008/01/28 22:25:00Z', then), expected);
       }
       date("2008/01/28 22:24:30Z", "just now");
       date("2008/01/28 22:23:30Z", "1 minute ago");
       date("2008/01/28 21:23:30Z", "1 hour ago");
       date("2008/01/27 22:23:30Z", "Yesterday");
       date("2008/01/26 22:23:30Z", "2 days ago");
       date("2007/01/26 22:23:30Z", undefined);
     });
     function domtest(name, now, first, second) {
       test(name, function() {
         var links = document.getElementById('qunit-fixture').getElementsByTagName('a');
         equal(links[0].innerHTML, 'January 28th, 2008');
         equal(links[2].innerHTML, 'January 27th, 2008');
         prettyDate.update(now);
         equal(links[0].innerHTML, first);
         equal(links[2].innerHTML, second);
       });
     }

     domtest("prettyDate.update", '2008-01-28T22:25:00Z', '2 hours ago', 'Yesterday');
     domtest("prettyDate.update, one day later", '2008-01-29T22:25:00Z', 'Yesterday', '2 days ago');
    </script>
</head>
<body>
  <div id="qunit"></div>
  <div id="qunit-fixture">
    <ul>
      <li class="entry" id="post57">
        <p>blah blah blah…</p>
        <small class="extra">
          Posted <span class="time"><a href="/2008/01/blah/57/" title="2008-01-28T20:24:17Z">January 28th, 2008</a></span>
          by <span class="author"><a href="/john/">John Resig</a></span>
        </small>
      </li>
      <li class="entry" id="post57">
        <p>blah blah blah…</p>
        <small class="extra">
          Posted <span class="time"><a href="/2008/01/blah/57/" title="2008-01-27T22:24:17Z">January 27th, 2008</a></span>
          by <span class="author"><a href="/john/">John Resig</a></span>
        </small>
      </li>
    </ul>
  </div>
</body>
</html>

For practice, I converted the QUnit tests to Jasmine. The first part of the test was easy, but I wanted a clean way to do the HTML fixture-based tests for prettydate.update too. Jasmine-JQuery gives you a handy way to have HTML fixtures. Here’s what my code ended up as:

spec/DateSpec.js

describe("PrettyDate.format", function() {
    function checkDate(name, then, expected) {
        it(name, function() {
            expect(prettyDate.format('2008/01/28 22:25:00Z', then)).toEqual(expected);
        });
    }
    checkDate("should display recent times", '2008/01/28 22:24:30Z', 'just now');
    checkDate("should display times within a minute", '2008/01/28 22:23:30Z', '1 minute ago');
    checkDate("should display times within an hour", '2008/01/28 21:23:30Z', '1 hour ago');
    checkDate("should display times within a day", '2008/01/27 22:23:30Z', 'Yesterday');
    checkDate("should display times within two days", '2008/01/26 22:23:30Z', '2 days ago');
});
describe("PrettyDate.update", function() {
    function domtest(name, now, first, second) {
       it(name, function() {
           loadFixtures('test_fixture.html');
           var links = document.getElementById('qunit-fixture').getElementsByTagName('a');
           expect(links[0].innerHTML).toEqual('January 28th, 2008');
           expect(links[2].innerHTML).toEqual('January 27th, 2008');
           prettyDate.update(now);
           expect(links[0].innerHTML).toEqual(first);
           expect(links[2].innerHTML).toEqual(second);
       });
    }
    domtest("prettyDate.update", '2008-01-28T22:25:00Z', '2 hours ago', 'Yesterday');
    domtest("prettyDate.update, one day later", '2008-01-29T22:25:00Z', 'Yesterday', '2 days ago');
});

jasmine.html

<!DOCTYPE HTML>
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <title>Jasmine Spec Runner v2.0.2</title>

  <link rel="shortcut icon" type="image/png" href="lib/jasmine-2.0.2/jasmine_favicon.png">
  <link rel="stylesheet" type="text/css" href="lib/jasmine-2.0.2/jasmine.css">

  <script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
  <script type="text/javascript" src="lib/jasmine-2.0.2/jasmine.js"></script>
  <script type="text/javascript" src="lib/jasmine-2.0.2/jasmine-html.js"></script>
  <script type="text/javascript" src="lib/jasmine-2.0.2/boot.js"></script>
  <script type="text/javascript" src="jasmine-jquery.js"></script>

  <!-- include source files here... -->
  <script type="text/javascript" src="prettydate.js"></script>

  <!-- include spec files here... -->
  <script type="text/javascript" src="spec/DateSpec.js"></script>

</head>

<body>
</body>
</html>

I’m looking forward to learning how to use Jasmine to test Angular applications, since behaviour-driven testing seems to be common practice there. Little steps! =)