Concise writing helps us share ideas, but we hamstring ourselves by trying to appear “substantial”. Let’s figure out how to avoid this trap.

Benefits of Brevity

Concise, efficient writing has non-obvious benefits:

We maximize information density.

We can hold about 7 digits in memory. Given limited room, a few powerful thoughts are better than a single dilute one.

What’s better: “x is the sum of two times y and three times z” or “x = 2y + 3z”?

Concise thoughts are more understandable. (By the way, math used to be written in English, as above. Egads.)

We respect the reader.

Long-winded diatribes are about the author: listen to me and look at what I know. Effective communication is about the reader: I’ve distilled hundreds of pages to these essential insights.

Information is everywhere, and I can eventually understand a topic by reading dozens of mediocre books. But time is limited — give me the source that communicates the most understanding in the least time.

We communicate raw thought.

Writing isn’t about words, it’s about recreating ideas:

• Idea in my head => words are written => words are read => idea in your head

With good writing we hear the author’s voice, not our own thoughts deciphering their message. The ideal of communicating raw ideas appears in programming, design, art and even humor (”Brevity is the soul of wit”).

Obstacles to Brevity

If brevity is so desirable, why don’t we do it?

Schoolchild Guilt (aka the 10-page paper)

School assignments ask for pages of text, not ideas. The teacher really wants an essay with 3 meaningful insights, but that’s tough to specify. So instead he asks for a 10-pager, hoping some ideas are buried inside.

The assignment is easily gamed: take a few scattered thoughts, bump up the font and margins, and tada, we have 10 pages. We know this isn’t what the teacher wants, but it satisfies the letter of the law.

An analogy: A king secretly wants treasure. He asks his subjects to bring him a ton of dirt each, hoping for gems inside. They do, and on average there’s a single gem in each pile — but the king spends hours clawing through the dirt.

One day a peasant sees a lone gem on the beach. But because the king asked for dirt (he’ll be punished if he only brings a handful of “stuff”), he buries the gem in an enormous pile and delivers that to the king, who spends hours trying to find the jewel.

Is that what the king wanted? We writers are the peasants that bring material for you to sift through!

Getting Our Money’s Worth

Thought experiment: you see two reference books, one at 100 pages and the other at 200. Do you wonder if the smaller book could be concise and well-written, or do you immediately assume “bigger is better” and reach for the tome?

And that’s why publishers pad their books — we reward those with the most words, not the best ones. It’s akin to judging a portrait by how much paint was used, or a song by its length.

Brevity and Substance

My “brevity” means economy of words, saying what’s necessary and no more. “Necessary” could be a paragraph or 50 pages; either is fine.

The key is delivering gems, not dirt. When writing, you know what you’re providing .

I still struggle with accepting that it’s ok, nay good, to share a single, concise thought if you think it’s a gem. There’s no need to pad to make it seem “substantial”.

Does anyone think the 278-word Gettysburg address isn’t meaty enough? Should Lincoln have stretched it out a bit?

Expert’s Guilt (The sky is not blue)

Brevity’s enemy is an armada of “helpful” information. Consider this: is the sky blue?

Well, it’s black at night. And orange at sunset/sunrise. And grey when cloudy. In fact, it’s more likely to be non-blue than blue!

My goodness, I could never say “The sky is blue” without a 3-page disclaimer, lest an expert meteorologist have my head.

No. Writing riddled with caveats is like the “Are you sure? Really sure?” dialogs we hate in software: yes, yes, we get it!

Models are simplifications, we all know this: assume an intelligent reader and don’t encumber your writing to satisfy every critic. Corner cases are exactly that, and should live away from the main text.

Examples of Brevity

I learn by reflecting on great examples — what makes them tick?

Computers and Programming

Ruby has wonderful shortcuts for everyday tasks.

value = parameter || getValue() || "default"

Which means “try to use parameter, then try getValue(), and if all else fails assign a default”. Ruby was the first language I felt I was reading without notational cruft getting in the way.

Kernighan and Ritchie’s The C Programming Language is the gold standard of technical manuals. Concise and useful, it has no desire to satisfy some publisher’s pagecount requirement: “C is not a big language, and it is not well served by a big book.”

Don’t Make Me Think! is an excellent usability guide. The title is the summary: keep things brainlessly easy. The book expands with examples, yet remains brief.

The unix command line (”cat foo.txt | sort | uniq -c | sort -rn”) is wonderfully concise and powerful: it’s hard to express the above more simply (output a file, sort the lines, count the unique ones, and sort again by that count in descending order).

Mathematics

As we saw with English vs. arithmetic, expressive notation helps us focus on the idea being conveyed.

Consider the difference between decimal and Roman numerals: how can you use math when it takes 5 minutes to decode MCMXCVII times XLII? Decimal notation is one of our greatest discoveries.

Quotes

Why do we love quotes? They are distilled thoughts! Great quotes help us experience an idea without getting lost in verbiage.

Some favorites:

• “I have made this letter longer than usual because I lack the time to make it shorter.” –Blaise Pascal (It’s easier to plop down dirt than to dig through and pull out the gems)

• “Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell.” –William Strunk Jr. (Efficiency is universally appreciated)

Economy of Motion

Great athletes and musicians are efficient. They move less and waste less than the rest of us, and do more with the same amount of time. Concise thoughts require less mental energy to understand.

Headlines

Top 10 lists grab our attention. Why? They imply someone has found the gems: we sifted through dozens of items and are bringing you the best. Unfortunately, these headlines have been abused to mean “Here are 10 random things”.

Cheatsheets

Cheatsheets are pure gems, going from A to B without distraction. The key is knowing the background of your audience. A physics cheatsheet is great for reference, not learning.

Final Thoughts

Reflection helps develop a learning philosophy. I discovered that my fear of not having enough substance was based on measuring dirt. Brainstorming, writing down ideas, and leaving the essentials is more than ok — it’s my ideal.

Remember: is our goal to satisfy a length requirement, impress with our vocabulary, or communicate effectively? Do readers a favor and give ‘em your best gems.

• Understand regular version control
• Understand distributed version control

Along with a book, tutorial and cheatsheet, here are the insights that helped git click.

There’s a staging area!

Git has a staging area. Git has a staging area!!!

Yowza, did this ever confuse me. There’s both a repo (”object database”) and a staging area (called “index”). Checkins have two steps:

• git add foo.txt
  • Add foo.txt to the index. It’s not checked in yet!
• git commit -m "message"
  • Put staged files in the repo; they’re now tracked
  • You can “git add --update" to stage all tracked, modified files

Why stage? Git’s flexible: if a, b and c are changed, you can commit them separately or together.

But now there’s two undos:

• git checkout foo.txt
  • Undo local changes (like svn revert)
• git reset HEAD foo.txt
  • Remove from staging area (local copy still modified).

Add and commit, add and commit — Git has a rhythm.

Branching is “Save as…”

Branches are like “Save as…” on a directory. Best of all:

• Easily merge changes with the original (changes tracked and never applied twice)
• No wasted space (common files only stored once)

Why branch? Consider the utility of “Save as…” for regular files: you tinker with multiple possibilities while keeping the original safe. Git enables this for directories, with the power to merge. (In practice, svn is like a single shared drive, where you can only revert to one backup).

Imagine virtual directories

I see branches as “virtual directories” in the .git folder. While inside a physical directory (c:\project or ~/project), you traverse virtual directories with a checkout.

• git checkout master
  • switch to master branch (”cd master”)
• git branch dev
  • create new branch from existing (”cp * dev”)
  • you still need to “cd” with “git checkout dev”
• git merge dev
  • (when in master) pull in changes from dev (”cp dev/* .”)
• git branch
  • list all branches (”ls”)

My inner dialogue is “change to dev directory (checkout)… make changes… save changes (add/commit)… change to master directory… copy in changes from dev (merge)”.

The physical directory is a scratchpad. Virtual directories are affected by git commands:

• rm foo.txt
  • Remove foo.txt from your sandbox (restored if you checkout the branch again)
• git rm foo.txt
  • Remove foo.txt from current virtual directory
  • Gotcha: you need to commit that change!

Know the current branch

Just like seeing your current directory, put the current branch in your prompt!

In my .bash_profile (modified from here):

parse_git_branch() {
    git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/'
}

export PS1="\[\033[00m\]\u@\h\[\033[01;34m\] \W \[\033[31m\]\$(parse_git_branch) \[\033[00m\]$\[\033[00m\] "

Visualize your branch structure

Git leaves branch organization to you. Nvie.com has a great branch strategy:

• Have a mainline (master). Mentally it’s on the far right.
• Create branches (master -> dev) and subbranches (dev -> featureX). The further from master, the crazier.
• Only merge with neighbors (master -> dev -> feature X, or featureX -> dev -> master)

Stay sane by choosing a branch layout up front. I have a master tracking a svn project, and dev for my own code. In general, master is clean so I can branch anytime for one-off fixes.

Understand local vs. remote

Git has local and remote commands; seeing both confused me (”When do you checkout vs. pull?”). Work locally, syncing remotely as needed.

Local data

• git init
  
  • create local repo
  • use git add/commit/branch to work locally

Remote data

• git remote add name path-to-repo
  • track a remote repo (usually “origin”) from an existing repo
  • remote branches are “origin/master”, “origin/dev” etc.
    
• git branch -a
  • list all branches (remote and local)

• git clone path-to-repo
  • create a new local git repo copied from a remote one
  • local master tracks remote master
• git pull
  • merge changes from tracked remote branch (if in dev, pull from origin/dev)
• git push
  • send changes to tracked remote branch (if in dev, push to origin/dev)

Why local and remote? Subversion has central checkins, so you avoid committing unfinished work. With git, local commits are frequent and you only push when ready.

GUIDs are GOOD

Git addresses information by a hash (GUID) of its contents. If two branches are the same, they have the same GUID (and vice versa).

Why’s this cool? We can create branches independently, merge them, and have a common GUID. No central numbering needed. Usually, we just compare the first few digits: “Are you on a93?”.

Tips & Tricks

For your .gitconfig:

[alias]
        ci = commit
        st = status
        co = checkout
        oneline = log --pretty=oneline
        br = branch
        la = log --pretty=\"format:%ad %h (%an): %s\" --date=short

There are some GUI tools for git, but I prefer to learn via the command line. Git is opinionated software (which I like), and analogies help me understand its world view.

• The “bag of formulas”: memorize ‘em and move on
• The anal-retentive, rigorous treatment: written by math robots, for math robots!
• The happy smiles tour: oversimplifications without examples (Calculus helps scientists solve problems!)

No, nyet, nein! I know what I need: intuition (What does it really mean?) followed by examples to back it up. I want a calculus series that lets calculus be calculus — wild, interesting, and fun.

The Explanatory Approach

I started writing in a vacuum, but realized I don’t remember calculus. I need a refresher — in fact, I need the insights I want to share! These articles are for us both (it’s what I’d want to relearn the subject), and here’s my approach:

• I’m reading Elementary Calculus: An Infinitesimal Approach [free pdf]. It teaches calculus using its original approach (infinitesimals), not the modern limit-based curriculum. My goal is intuition, so this works well.

• As I study the chapters, I’ll share the insights I find and the concepts I struggled with.

• I’ll sprinkle examples along the way. They’re a gut check, not the focus (if you want practice problems, the book has plenty).

It’s a lack of insights, not information, that makes calculus hard. We don’t need another course repeating the definitions that confused us the first time (Here’s the definition of a limit, again!).

We shouldn’t be struggling with the true meaning of a subject centuries after its invention. This is my intuition-laced hat in the ring.

The Calculus Articles

The goal is to be concise, informal, and fun. Dabble, skim and ignore the examples if needed — focus on the insights. The elegance of calculus can be appreciated progressively: we don’t need astrophysics to enjoy a starry night.

Learning Math

• Developing Your Intuition For Math

Calculus Overview

• Prehistoric Calculus: Discovering pi
• A Gentle Introduction To Calculus

Small numbers: Limits and Infinitesimals

• Learning Calculus: Overcoming Our Artificial Need for Precision
• Understanding the need for small numbers (in progress)

Measuring Changes: Derivatives

Accumulating Changes: Integrals

• A Calculus Analogy: Integrals as Multiplication

This post is the table of contents for the series. Happy math.