On this page:

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! =)

Emacs: Limiting Magit status to a directory

I’m probably using Git the wrong way. In addition to the nice neat repositories I have for various projects, I also sometimes have a big grab-bag repository that has random stuff in it, just so that I can locally version-control individual files without fussing about with Emacs’ numbered version systems. Sometimes I even remember to organize those files into directories.

When you have a Git repository that’s not one logical project but many little prototypes, using Magit status to work across the entire project can sometimes mean running into lots of distracting work in progress. I wanted a way to limit the scope of Magit status to a specific directory.

Here’s the experimental code I came up with:

      (defvar sacha/magit-limit-to-directory nil "Limit magit status to a specific directory.")
      (defun sacha/magit-status-in-directory (directory)
        "Displays magit status limited to DIRECTORY.
Uses the current `default-directory', or prompts for a directory
if called with a prefix argument. Sets `sacha/magit-limit-to-directory'
so that it's still active even after you stage a change. Very experimental."
        (interactive (list (expand-file-name
                            (if current-prefix-arg
                                (read-directory-name "Directory: ")
                              default-directory))))
        (setq sacha/magit-limit-to-directory directory)
        (magit-status directory))

      (defadvice magit-insert-untracked-files (around sacha activate)
        (if sacha/magit-limit-to-directory
            (magit-with-section (section untracked 'untracked "Untracked files:" t)
              (let ((files (cl-mapcan
                            (lambda (f)
                              (when (eq (aref f 0) ??) (list f)))
                            (magit-git-lines
                             "status" "--porcelain" "--" sacha/magit-limit-to-directory))))
                (if (not files)
                    (setq section nil)
                  (dolist (file files)
                    (setq file (magit-decode-git-path (substring file 3)))
                    (magit-with-section (section file file)
                      (insert "\t" file "\n")))
                  (insert "\n"))))
          ad-do-it))

      (defadvice magit-insert-unstaged-changes (around sacha activate)
        (if sacha/magit-limit-to-directory
            (let ((magit-current-diff-range (cons 'index 'working))
                  (magit-diff-options (copy-sequence magit-diff-options)))
              (magit-git-insert-section (unstaged "Unstaged changes:")
                  #'magit-wash-raw-diffs
                "diff-files"
                "--" sacha/magit-limit-to-directory
                ))
          ad-do-it))

      (defadvice magit-insert-staged-changes (around sacha activate)
        "Limit to `sacha/magit-limit-to-directory' if specified."
        (if sacha/magit-limit-to-directory
            (let ((no-commit (not (magit-git-success "log" "-1" "HEAD"))))
              (when (or no-commit (magit-anything-staged-p))
                (let ((magit-current-diff-range (cons "HEAD" 'index))
                      (base (if no-commit
                                (magit-git-string "mktree")
                              "HEAD"))
                      (magit-diff-options (append '("--cached") magit-diff-options)))
                  (magit-git-insert-section (staged "Staged changes:")
                      (apply-partially #'magit-wash-raw-diffs t)
                    "diff-index" "--cached" base "--" sacha/magit-limit-to-directory))))
          ad-do-it)))

Now I can bind C-x v C-d to sacha/magit-status-in-directory and get something that lets me focus on one directory tree at a time. You can see my config in context at http://sachachua.com/dotemacs#magit

It feels like I’m probably trying to do things the Wrong Way and I should probably just break things out into separate repositories. Even though I realized this early on, though, I ended up digging into how to implement it just for the sheer heck of seeing if Emacs would let me do it. =) I don’t know how often I’ll use this function, but it was a good excuse to learn more about the way Magit works.

It took me an hour to find my way around magit.el, but that’s more my fault than the code’s. At first I tried to override magit-diff-options, but I eventually remembered that the paths need to come at the end of the command line arguments. (I had a cold! My brain was fuzzy!) It was fun poking around, though. Looking forward to learning even more about Magit!