Humorous Writing for the Lazy and Impatient

Tips for and stories about writing for developers.

This blog post is part of the Trailhead content creator series. Follow The Trailblazer publication to read the entire series.

I’ve had the privilege of writing for Trailhead since its beginning. Although we got many things right, we didn’t have everything dialed in from the start. One of those things is the “Trailhead Tone,” which has evolved a fair bit since the beginning.

My first module was Visualforce Basics, and a quick re-read confirms what I suspected. I’m still happy with the writing — it’s straightforward, friendly, and approachable. Exactly what we aimed for in a launch module. But there isn’t a lot of personality there. No quirkiness, no humor.

Indeed, when we launched Trailhead the prevailing school of thought discouraged humor or quirk in the developer-focused modules. What’s funny about code? The thinking was that it would turn developers off. And if we’re talking about the humor you find in the Catter or Event Monitoring modules, you might be right.

Let me be clear: Those modules are terrific work. Event Monitoring, with its cast of characters including Rob Burgle, turns a pretty dry topic — reading logs — into a fun story. I still think it has the best lead sentence in all of Trailhead. And Catter is my favorite module. Not because the author is our editor-in-chief (hi Chris!), but because I laughed from start to finish while earning that badge.

But sustained over a module of eight or nine units, like Visualforce Basics or Lightning Components Basics, that level of cleverness starts to be a bit much. (It’s also really, really hard to write.)

So I don’t try. Humor is hard, and I’m lazy — in the Larry Wall sense. I take a different approach to adding levity and personality to the material I write. I’ll share a couple of tips and stories to explain what I mean.

Know Your Audience

I was a software developer before I was a technical writer, and I’ve worked directly with engineers for almost 30 years. There are stories, metaphors, turns of phrase, and people that most developers know about, and making a reference to them at the right moment will usually get an amused quirk of the mouth, if not a snort. Even as they baffle non-developers — like my editors, who are probably wondering who this “Larry Wall” is.

Note: If you’re a developer and you don’t know about Larry Wall’s three great virtues of a programmer, I recommend reading up on them. They might change the way you approach writing software.

Take Something Hard and Make It Absurd Instead

Here’s a true story from writing the Lightning Components Basics module. I’m a night owl, and I was working some crazy hours to get the module finished for TrailheaDX, the big Salesforce developer conference in June. And late at night I ran headlong into the wall that was describing how to set attributes on <aura:attribute> to define component attributes. (Yes, it’s a brain-twister.)

I must have tried a dozen different ways of writing it, and could not get it right. I couldn’t yell out loud, because that would wake people up. So I started banging in angry emoji icons. And … it kinda worked! So I decided to ̶m̶a̶k̶e̶ ̶m̶y̶ ̶f̶r̶u̶s̶t̶r̶a̶t̶i̶o̶n̶ ̶y̶o̶u̶r̶ ̶f̶r̶u̶s̶t̶r̶a̶t̶i̶o̶n̶ put that awkwardness into the unit itself. And so, Trailhead got its first emoji.

An attribute by any other name…

It’s awkward because we’re talking about three different kinds of “attribute,” all related to — or tangled with — each other. I wanted to say “This is hard. It’s OK if it seems a bit hard. You’ll get it. Let’s look at an example.” And to say it in a friendly way. Who doesn’t find 😀 friendly?

Don’t Force It. Be Open. Take the Occasional Risk.

Humor is hard, and I’m frankly not that good at it. So the most important “funny” thing I do when writing is to not try too hard to be funny. If I start thinking I need a joke every unit, or a cadence of concept-concept-joke, I’m going to get blocked before I get to the second joke. Which, as any writer will tell you, is not funny.

The flip side of not forcing it is being open to seeing something when it drops in your lap. The emoji passage is mildly amusing. Carly Rae Jepsen, though, had me giggling for hours.

I was working on the server-side controllers unit of that same Lightning Components Basics module, and had gotten about halfway through it. And the next topic was the callback function for handling the server’s response. Callback functions are, in computer science terms, function pointers, and pointers break people. They’re hard to explain, too, and I was dreading writing it. Time for a break!

As I was getting up from my desk, a song that had been bouncing around in my head for days popped in again. ♫ Here’s my number, so call me maybe. ♫

I thought, ha, that’s kind of a callback!, and was about to head out for a late lunch when … wait a second, there’s something there. I sat back down and typed a note into my draft. Then I went out for lunch … and followed it up with a nap. By the time I got back to writing it was hours later, and my brain had been percolating the idea pretty vigorously. When I re-read my note and thought through how to write it, I started giggling. And had to take periodic breaks to laugh the entire time I was writing it.

Since I don’t write blog posts without code samples, let me share the pseudocode I explained with a song:

doInit: function(component, event, helper) {
    // Load expenses from Salesforce
    var action = component.get("c.getExpenses");
    action.setCallback(
        // Here’s my number,
        // Call me maybe
    );
    $A.enqueueAction(action);
}

I’m probably a little too pleased with the result, and experienced JavaScript programmers, for whom callback functions are de rigueur, might find it a little much. But for folks who are relatively new to JavaScript and asynchronous programming, I think — hope — the explanation is both understandable and memorable. And, maybe, a bit fun too.

In the end, this is the Trailhead secret. People don’t respond to Trailhead because it’s funny, they respond because they’re having fun.

People don’t respond to Trailhead because it’s funny, they respond because they’re having fun.

That’s great news for me as a writer. Being “funny for developers” is really hard. But “having fun with my fellow developers” — I can do that all day.

Interested in learning more? Come to our session at Dreamforce and learn how to write the Trailhead way.

How to Write the Trailhead Way

• Tuesday, October 4; 2:30–2:50pm PT
• Moscone West, Admin Meadow Theater

Can’t make it in-person? The session won’t be streamed, but we’ll be posting the materials afterward on the Success Community in the Trailhead group.