/\ndy

Debugging the 500 Mile Email

What would you do if the big boss told you, with total conviction, that there was a problem with the email server, and he could not send email to anyone beyond a 500 mile radius.

And then you found out he was right.

In this classic tale of debugging you'll see what happened.

/\ndy

Christmas Warp Core Breach

Well we had an exciting Christmas day -- and very nearly burned the house down.

'Twas the afternoon past Christmas
But we'd no chance to get bored
An incredible stink arose--
A burning smell we could not ignore.

I dashed up to my office in such a flash
To see what was the matter,
This was no simple server crash!

I flung open the door and turned on the light
The room was filled with billowing toxic fumes,
Must have been burning all night.

In the back corner the UPS was steaming
Too hot to touch with my bare hands alone,
I grabbed oven mitts and dashed it outside
Dripping hot acid, smelling of brim-stone.

It had soaked into the rug, that nasty old fraud
Ruined my iso-box and splashed on my Quad
Soaked into my cables and stunk up the place
Acid spots on the floor and on my staircase.

We tore open the windows and started the fans,
In hope to recover our day's previous plans
But one thing led to another, and with a heavy frown
I ended the day unplugged, my system was down.

I called up the company, to complain of this lemon
They simply shrugged and replied,
"These things happen."

Okay the meter isn't exactly right, but you get the idea :-). Watch out for those battery-backup UPS boxes!

/\ndy

Jolt Award finalists...

They've just announced the 19th annual Jolt Product Excellence Awards, and I'm honored to report that Pragmatic Thinking and Learning is a finalist in the General Books category.

Congratulations to all the finalists!

/\ndy

Information scraps

A new article on Physorg.com, Digging out from piles of sticky notes describes a real problem: how do you manage and track a wide variety of disparate information? The real world isn't limited to to-do lists, phone numbers, and addresses. You may be interested in everything from guitar chords to notes on f-stops and shutter speeds to fantasy football rosters or drafts of ideas to blog.

These researchers point out that lightweight capture is important -- if takes too much time or effort, folks won't bother at all, and the information can get lost (or worse, relegated to a drooping sticky note on the side of your monitor). But the inherent problem, they note, is that we tend to use different applications depending on the sort of data we're working with. So you have a to-do list app for things to do, a calendar app for dates and reminders, and so on.

While they are working on the research and solutions, there's a very simple and effective solution that has worked very well for me: a personal wiki.

Instead of a web-based wiki, using something local. I prefer using a text editor in Wiki mode; Emacs came with a very usable wiki-mode, and you can do the same sort of thing in vi, or TextMate, or any editor that allows you to write sufficiently-rich macros.

Each page is unstructured plain text, so there are no limits to what you can add. By using WikiWords to link pages together, a structure to your notes will emerge that makes sense to you.

To make sure I don't lose notes that are time sensitive, I put special tags in the notes with dates, and a script runs through and builds up a calendar display and/or to-list from all the bits and pieces scattered through the wiki. Everything is stored in plain text, and is under version control (CVS, for historical reasons). It's a little crude, but it's effective.

/\ndy

Thanks to Mark Hutchinson for pointing out the article.

On Writing: It's Not the Words

While reviewing a manuscript the other day, something occurred to me, something that many authors (myself included) tend to forget: the words aren’t the important part. Writing is not about the words.

We get too attached to words. Especially the words we’ve slaved over and poured out on the paper. But good writing is not about the words; you can throw out all those words, and replace them with other words, and it can still mean the same thing. And as with code, throwing out all the words/code and starting over practically guarantees a better result. Let me explain.

I belong to a local songwriter’s association. Once a month, we meet and critique each other’s latest efforts (alas, I haven’t been participating as often as I’d like, but that’s what New Year’s Resolutions are for.) While critiquing other people’s lyrics and song structures, I’m constantly amazed at the similarities to the book writing process. Beginners make the same sorts of mistakes, and experts work their craft with similar subtlety.

Novice song writers (and sometimes those who should know better) tend to use too many words. Instead of showing the audience an idea, they feel compelled to tell the audience all about it. In detail, with all the articles, pronouns and other trappings of regular speech. But most good songs aren’t written that way; it’s generally not the same style as a novel or spoken speech.

Reminds me of an old limerick:

There once was a young poet named Stan
Whose poetry just wouldn’t scan
When asked why, he said in reply
“It’s because I try to fit as many words on the last line as I possibly can“

But here’s the thing. When writing a song, sometimes you have to rework the lyrics to fit the music, and sometimes you change the music to fit the words. To maintain a fixed rhyme scheme or meter, your choice of words can get quite restricted. And you know what? Not only is that a great exercise, but in the end the song has the same meaning. The words “don’t matter” in that there are many other words that would do, but we end up using these particular words because they rhyme, or have the necessary number of syllables and stress in the right place, and so on.

So what does this mean to writing in general?

Show, Don’t Tell

First, remember to show your audience what you want to convey, don’t just tell them about it. The difference is subtle, but important. Showing and explaining is much more direct than telling. Telling is monologue, and monotonous; a good book is a dialogue, and engaging.

I get a chuckle every time I see an author write, “I’d like to tell you all about xyzzy now.” Just tell me!

You don’t have to disclose everything you know about a subject. I’m sure the history of a technology and biographies of the major players involved is fascinating, but most of the time that sort of information just isn’t relevant to the topic at hand. Rip it out of the book, and save it for a blog post.

Map it out

Dave relates writing to the Hero’s Journey. But it’s all too easy to forget the whole “journey” part.

If a book is a journey, you need to start with a map. Not an outline of the topics you’re going to cover, but a map of where you’re taking the reader. As author you’re not just doing a brain-dump of information onto the paper, you’re taking the reader on a trip.

What are the landmarks you’ll see along the way? Is this the place where you’ll lead the reader up to the brink of the chasm and show them the steep cliffs before showing them the easy path down? Or are you going to lead them on the easy path, and point up to the menacing cliffs you avoided?

What will the reader feel along the way? Are you going to lose their attention across the boring vast plains in the middle? (Maybe you don’t want to cross those plains in that case :-) At each rest break, what can you do to keep them excited enough to continue the journey?

I find myself constantly asking authors to provide more roadmaps or markers for the journey. Tell me where we’re headed next. Remind me where we’ve been, what lies ahead, and how they are connected. Remind me what the important parts were that we just saw.

Before you start writing, before you think about an outline, think about a map—from the reader’s perspective. Draw out their journey, and begin to plan the sights you’ll see, the stopping points, which parts will be going uphill and difficult, and which parts will be downhill and easy.

Then you can start writing the words.

It’s an agile world, so of course you can (and should) go back and revise your map as needed.

In keeping with the plot/story analogy, you can also think of your map as a storyboard. Draw out the “scenes,” again from the reader’s perspective.

In keeping with the themes from Pragmatic Thinking and Learning, I will of course suggest that you hand-draw both the map and storyboards.

Sketching out what the journey will look like ensures that there is a journey. Otherwise, you may as well just be writing a dictionary…

It’s not the words

Finally, let me suggest that writing is not even about writing. It’s about re-writing. As many times as it takes. Maybe 5. Maybe 50. But that’s okay, because the actual words on the paper aren’t that important. Toss ‘em out, and try some others.

This is a first draft, by the way. So it likely has some of the very drawbacks I’ve pointed out :-) But maybe I’ll come back to it and revise it as needed.

This is version 1.0, as of 2008-12-09.

/\ndy

Science Failure and Cubicle Brain Death

A lot of people have told me that my recommendation for a cool notebook and/or pen is one of the top tips from my new book. Folks keep sending me others that they have found—notebooks in distressed leather, with waterproof paper, with steampunk etched covers, and more.

But this is not just some lame stationery affectation; things like the pen and paper you use, the decorations at your desk, the lighting and ceiling height of your cubicle all have a measurable effect on your cognitive processes. Here’s why.

You may have always heard that you start off with a certain number of brain cells, and that’s all you get. These brain cells might die off, but you’ll never get any new ones. Alcohol and aging can kill brain cells, which makes old age look pretty unappetizing—you’d be left with a lot less brain cells over time.

Fortunately, professor Elizabeth Gould thought otherwise. In a discovery that turned the field on its ear, she discovered neurogenesis—the continued birth of new brain cells throughout adulthood.

But here’s the funny part. The reason researchers had never witnessed neurogenesis previously was because of the environment of their test subjects. If you’re a lab animal stuck in a cage, you won’t grow new neurons.

If you’re a programmer stuck in a drab cubicle, you won’t grow new neurons either.

On the other hand, in a sensory-rich environment with things to learn, observe, and interact with, you will grow plenty of new neurons and new connections between them. A steampunk-etched notebook or a funky new pen is not just inspirational in some abstract way; the increased tactile sensory experience actually encourages growth of new neurons and stronger connections. (For example, Dan North gave me his Retractable Zebra Ball Point at a recent conference. Thanks Dan!)

For decades, scientists were misled because an artificial environment (sterile lab cages) created artificial data. Once again, as I harp on throughout the book, context is key.

Your working environment is a context as well. It needs to be rich in sensory opportunities, or else it will literally cause brain damage.

I don’t know about you, but I don’t have any neurons to spare!

/\ndy

Vote Agile

Tomorrow is election day here in the US, and if you haven’t already, I urge you to get out and vote.

Here in North Carolina, many of us have already voted—42% of all Democrats, 35% of all Republicans, and 30% of all independents have already voted. I voted last week, and the lines were running a half-hour to an hour even then.

In any race, from the presidential level to the local, I endorse the more Agile candidate. Agility is all about collaboration and adaptability, and taking a pragmatic attitude towards decision-making. Working with other people—even people you don’t particularly like—changing your approach to fit the problem at hand, and avoiding rigid dogma are all hallmarks of agility.

Does your candidate seem the thoughtful, collaborative type? Or more of a shoot-from-the-hip, impulsive sort?

Adaptability means changing your approach according to the situation; some derisively call that “flip flopping.” Frankly, that’s the stupidest charge I’ve ever heard. I want elected officials who will change their minds as needed. A stubborn resistance to accept and manage change is a proven recipe for disaster.

Following a narrow ideology is a dogmatic approach; it doesn’t work in business and I dare say it doesn’t work well in government either. The challenges facing us today require a flexible, adaptable, collaborative approach. A pragmatic and agile leader, not one steeped in repeating the same old dogma.

So please vote, and vote agile.

Thank you,

/\ndy

Always an exception...

For every rule, no matter how iron-clad it may seem, there’s always an exception.

Here’s an odd one that just came up, from a friend of a friend.

This is an era of Heightened Security and tightened border crossings. You must have your passport, you can’t carry a medium-sized tube of toothpaste into the US, and even soldiers carrying their M16 assault rifles on airplanes are relieved of their fingernail clippers, just in case things a crazed manicurist gets out of hand.

So true or false: if you are not a citizen of the US, you must have a passport to enter the US.

False. And here’s at least one intriguing exception.

The Micmac Indian tribe signed a treaty in 1796 which, among other things, declared the rights of indigenous peoples to travel—and trade—between the US and what is now Canada (it was a British territory at the time). That right became codified into law in the US in 1952, as part of the Immigration and Naturalization act.

The upshot is that today, Micmac indians may pass freely between the US and Canada, and can carry anything they please, including items that would normally be subject to taxation, etc., and do not have to carry a passport.

Now granted you usually don’t have to consider the ramifications of 200-year-old treaties when developing an application or gathering requirements.

But then again, there’s always an exception.

/\ndy

Test-driven Learning

While working on my new book, I came across an interesting idea that extends the popular agile notion of “test-driven development” to learning a new language or a new technology.

As it turns out, just studying something new over and over again doesn’t actually help you remember the material very well. However, if you keep testing yourself by trying to recall the material over and over, you’ll strengthen those connections in your brain.

Try to write a program in that new language you’re studying—-you’ll need to retrieve the key information to do so. Try to explain key parts of that new methodology to a colleague. Keep at the retrieval—-the testing of your knowledge. It’s kind of like “test-driven learning,” but in a good way, not like those horrible social studies quizzes in eighth grade. The idea is to practice retrieval, not input.

You can also take advantage of the spacing effect to make this all more effective.

Cramming, or studying a lot of information in a short amount of time, doesn’t work very well. We tend to forget things along an exponential curve, so spacing out your quizzing reinforces material much more effectively. For example, you might plan on retesting yourself along a 2-2-2-6 schedule: retest after two hours, two days, two weeks, and six months.

But that’s not the most efficient use of your time, especially with a large amount of material. Some facts and ideas will get memorized more easily, and others will need more work. Trying to keep track of an individual memory-decay curve for each fact you’re trying to memorize is too hard to do manually. But, hey, we’ve got this nifty computer that we can use.

Piotr Wozniak developed an algorithm to take advantage of the spacing effect, implemented in the commercial product SuperMemo (there’s an open source implementation available as well). It’s basically a souped-up flashcard program that keeps track of your performance and schedules retests according to an individual decay curve for each item.

It’s a great way to take advantage of the brain’s caching and archiving algorithms.

/\ndy

iPhone NDA lifted, we're back in!

Thanks to everyone who wrote me today--and I do mean every one :-)

With the lifting of the Apple NDA, we've gone ahead and released the iPhone SDK book and will be adding the missing iPhone chapter to the Core Animation book as well.

Thanks to Apple for realizing the impact this had on the developer community and finding a solution.

/\ndy