Technical Writing: Get Over Yourself

by Tim O'Brien

"Get Over Yourself" is advice I'd give to anyone trying to get into technical writing, it's the technology, it isn't you.

It isn't like I'm against tone and color in writing. I enjoy Jim Elliott and Brett McLaughlin, and I learn a lot from both of them. But, they are original, they earn it. I like Scott Oaks style, personable, but not over-friendly - Java Threads was one of the best books I've read. What I'm getting sick of is technical writing riddled with too many jokes, asides, stories about extreme sports. I don't like reading books where every chapter starts out with a story about hiking, or a Daily WTF story about some horrible mythical corporation full of complete idiots (I've worked there, I've written those chapters).

As an industry, I think we're too focused on personality these days. There's a class of conference rock stars that runs around and talks trends, and I think some of this has leaked over into the way we write technical books. Everybody writing a book these days wants to become "that guy with that blog that I saw at that conference". So in the tradition of Charles Nutter, I'm going to ask the question: Can you effective be one of those travellng conference rock stars? Write a series of well written books? And, be a formidable coder on several core open source projects at the same time? Probably not. So, let's stop building up the "Coder" as "Superman" idea.

These days, I'm ready for technical books with a little less personality and a lot more substance. Please don't get me wrong, there are certain authors I like personality from, I've already listed a few whom I read, but whenever I come along a new technical book these days I'm looking for technical content, not a new best friend. Antisocial? Yeah. Totally, I'm the guy at Starbucks that doesn't appreciate the small-talking Barista. Alone? No, I think anyone heads-down at work, reading a book about something like Ant, wants a concise, easy-to-read reference that keeps the chitchat to a minimum.

I'm tired of your funny technical stories and your metaphors: please, just the facts. OK, wait, calm down. I'll read and enjoy the witty stories, as long as the ratio of hard technical content to witty stories is greater than 10:1.

It's a little harsh, sure. But, I don't think I'm alone in this idea. I was just talking to someone who bought a new book on Ruby the other day. He told me that while it was informative, he found it difficult to scan. Difficult to pick out the one or two sentences he needed to read in 5 minutes. I can't say I haven't had that happen to me lately..... I'm turning down the color commentary dial at least for the next few books.

PS: It is also a message I'd give to the subjects of this photo in a recent Wired article. Vamping coder rock stars. I'm sure the persons pictured in this article had no control over the Wired photographer, but reading this makes me want to write more Java. Honest, a picture like that makes me want to attend less conferences, write more books, and get heads down into some coding.

Growing tired of the rock stars in programming that hire professional photographers to bring dramatic lights to the studio so they can looked seductively into the camera for some Ruby on Rails blog they are hosting (no DHH I'm not talking about you). I think we're straying from technology and getting too much into personality. (Ironic, where's the technology in this post.)

(For the record, this is about no one in particular. Matt, this isn't about you. Raible is someone I read, listen to and I follow his recommendations frequently. Charles Nutter, also not about you. If I were president, Charles Oliver Nutter would be in my cabinet as the first Secretary of Dynamic Languages. This is about everyone. And, before I make DHH curse at me, this isn't about you, I'm sure you find that photo as ridiculous as we all do. Hell, people, this is about me.)


Ray Krueger
2008-03-14 12:19:25
This article, it's about me isn't it?
Damn you O'Brien!!!!111oneone
Tim O'Brien
2008-03-14 13:19:50
Ray, what are you doing at a computer, it's 60 degrees in Chicago, and the Sun is out. And, Ray, actually this post was all about you. :-|
2008-03-14 13:39:06
Tim O'Brien
2008-03-14 13:41:16
@Jeff, word!
Don Denoncourt
2008-03-14 14:39:45
Here here. When I read a technical book and say to myself "who is this guy? I have to meet him: I wish I could code and write as well as him" it's because their writing is concise. Not because they use a kayak analogy in every chapter. I've published hundreds of articles and several books and I too had to "get over it" to improve my writing.
PS: If you'd like my professional photo, let me know.
2008-03-14 19:16:57
Ummm, maybe you should read your own writing before you start complaining about other people's writing. I couldn't get past the first couple paragraphs due to the poor grammar.

"But, they are original, they earn it."

"Can you effective be one of those travellng conference rock stars?"

Those were just in the first two paragraphs. Yikes.

Shawn Lauriat
2008-03-14 21:41:57
@saber: Blog posts don't generally have technical editors, peer reviewers, and copy editors behind the scenes.

Personally, I second agree with Tim and tried to write my book (blatant plug for Advanced Ajax, ISBN-10: 0131350641/ISBN-13: 978-0131350649) with this frame of mind. I don't buy technical books for jokes, analogies, or small talk. I never go back to a technical resources because I desperately need to find out what happened to a pet store - I need to find out how something works, why something works (or doesn't), or example code.

George Jempty
2008-03-15 05:30:49
After reviewing a rough draft, I recently performed a subsequent review of the next draft of a tech manuscript by a renowned consultant, and for the second time I advised against self-aggrandizing statements. This particular author is old school rather than a rock star: to his admonition "all in good time, dearie" (can you imagine DHH writing that?), I responded "Barftastic". While I hope the irony of my response was not lost, for the most part I was much more straightforward, and to tell the truth, I believe I have more of a chance of getting through to this author than to one of the new rock stars or their ilk.
2008-03-15 07:54:05
It's a simple thing called proofreading. Anyone who is going to write an article critiquing other people's writing should at least make sure their article isn't filled with grammatical errors and misspellings.
Tim O'Brien
2008-03-15 07:58:37
@saber, I is so sorrys for the spellings mistakes.... go jump in a f$#king lake saber, I'm dyslexic and don't care about the odd spelling and grammar problem here. You do, so don't read my blog. I'm happy to have wasted your time.

@Shawn, I just purchased your book.

@George, my first book was full of stories. By the time I got around to writing the second, I was paired up with Vincent Massol. My first few drafts were full of asides and jokes, his response was, "Really? You really want to subject people to this?" He was right and it took feedback like this to convince me to avoid "telling stories".

Tim O'Brien
2008-03-15 08:02:09
@saber, if it makes you feel any better, I'm going to inject errors into future posts just to get you riled up. Also, you are the only one on the thread not owning up to an identity. Let's see who is this mysterious poster from Atlanta?
Saber, Lord of the Kingdom of Atlanta
2008-03-15 08:44:28
@Tim: I'm not sure why you're interested in finding out my identity, but I can only assume it's so you can hunt through Atlanta (a city in which I don't even live, I might add) and throw sentence fragments and misspelled words at me.
Tim O'Brien
2008-03-15 09:04:45
@saber, it's ridiculous that people leave posts on these blogs, but don't have the spine to supply a real email address ( or a real name. Oh, but they only do so when they have something bad to say. *surprise!*
Shawn Lauriat
2008-03-15 15:33:47
@Tim: Sweet! Feel free to ask questions or send comment/corrections.
Mark Rosenthal
2008-03-15 16:15:58
I've been thinking the same thing for years. Technical documentation is not a novel. When I'm reading documentation, my attitude is like on the old Dragnet TV show: "Just the facts, ma'am. Just the facts!" Lately I'm much more inclined to learn from a Nutshell book than a 1,000 page tome. Even some of the Nutshell books have gotten a bit bloated.
Pieter Vos
2008-03-15 16:52:21
I don't entirely agree with you Tim, I personally think there are 2 types of books, references, which are the ones you bring into work to look something up if you need it, or non-reference technical books (I don't know what else to name them), the ones you can sit down and read to learn about something and that doesn't read like a phonebook. In the latter case, I think anecdotes and personality is a good thing, as it makes for lighter reading, and making me feel at least a bit less geeky for reading it at bed-time :P
2008-03-18 10:18:48
Totally agree!
Each day I like more of technology and less of technicians.
Carla Schroder
2008-03-18 10:27:53
I like a bit of personality and humor, but not at the expense of clear, well-organized content. Leave the ego at home, please. Dropping F-bombs is idiotic and juvenile, and self-aggrandizing tales of epic beer-drinking or other dopey, off-topic pastimes are pointless. Save it for "Animal House: Partyin' The Nursing Home". A classic example of a potentially fascinating story spoiled by too much ego is "Takedown" by Tsutomu Shimomura. This is what it says on Amazon:

"On Christmas Day 1995, a daring cybercriminal used a new, dangerous, and clever method to gain access to the home computer of the world's greatest computer security expert. The hero, as a matter of honor, set out to find the devious mastermind who violated his privacy and discovered that it was none other than cyberspace's Public Enemy Number One."

Erp. And it's all downhill from there, with way too many details from the hero's personal life (hot tubbing with hot babez, his exquisite taste in food, decor, dress, spirituality, and everything else), and not nearly enough details about the pursuit and capture of Mitnick. You know, the stuff the book is supposed to be about.

I think Larry Wall is a great example of an author who infuses his writing with his own personality and humor in a way that illustrates the subject, and helps you understand it better. Try this example from the "Open Sources: Voices from the Open Source Revolution" book:

"In this case, the Chinese have traded learnability for portability. Does that sound familiar?

Chinese is not, in fact, a single language. It's about five major languages, any of which are mutually unintelligible. And yet, you can write Chinese in one language and read it in another. That's what I call a portable language. By choosing a higher level of abstraction, the Chinese writing system optimizes for communication rather than for simplicity. There are a billion people in China who can't all talk to each other, but at least they can pass notes to each other.

Computers also like to pass notes to each other. Only we call it networking...That's where Unicode and XML come in. Unicode is just a set of universal ideographs so that the world's computers can pass notes around to each other..."

And it goes to talk about onions, tie-dye, Tao, growth rings, pi, and all kinds of crazy stuff. Which have little to do with the nuts and bolts of writing programs in Perl, but everything to do with designing them intelligently.

2008-03-24 16:27:48
I could not agree more. We write code for hours at my company, everything from virtual worlds to database to flash and graphic implementation; I can't find time to eat lunch let alone travel to guest speak at a conference. On the other hand, I write killer apps that get noticed and make my clients over the top success. But I do it for the glory of the client not for my own personal glorification.
Frank Jensen
2008-03-28 05:15:27
I agree that many books are littered with "personality". But the problem is that it is mixed together with the technical stuff. Which means that the "fluff" is difficult to avoid. Why can't authors separate this two tings.

"Head First Design Patterns" does this. It contains a lot of the stuff you don't like, but it is so easy to skip ut, you don't have to care.

ella lowe
2008-03-28 18:44:15
hi my name is ella and this is wha i say when pepol are winging i say billd a brig cry a river and get over it.

from ella

Pat Kerpan
2008-04-02 17:13:20
The beauty of blogs is the timeliness and spontaneity. This means occasional keyboard typos and mental typos. They don't diminish the written piece in impact, nor in its ability to be enjoyed or considered.

Thanaks for teh post Tim.

Emily Cotlier
2008-04-10 18:20:57
I agree that, for technical writing proper, less add-ons and quirky stories equals more efficient documentation. A friend of mine who is a novelist was trying to break into technical writing, and she asked me for advice on changing her writing style. I told her that her personal fiction writing was like a glass of fine wine - its personality, nuances, and flavor were why somebody would drink it. But technical writing is like a glass of water. People drink water for a purpose, because they're thirsty, they need to get hydrated, and they don't like odd flavors or amoebas in their water, they're just a distraction. People consult technical documentation for a purpose - because they need information - and it should be as simple and rewarding as getting that metaphorical glass of water.

I do agree with other posters who are saying that, for a technical education book, some personality and anecdotes can be valuable, because they keep the reader invested in the book.