Writing, Speaking, and Programming

Joel Spolsky's 2005 edition of Advice for Computer Science College Students has one bit of advice that applies to all programmers, no matter how long ago they graduated from college:

Would Linux have succeeded if Linus Torvalds hadn't evangelized it? As brilliant a hacker as he is, it was Linus's ability to convey his ideas in written English via email and mailing lists that made Linux attract a worldwide brigade of volunteers.

Have you heard of the latest fad, Extreme Programming? Well, without getting into what I think about XP, the reason you've heard of it is because it is being promoted by people who are very gifted writers and speakers. Even on the small scale, when you look at any programming organization, the programmers with the most power and influence are the ones who can write and speak in English clearly, convincingly, and comfortably. Also it helps to be tall, but you can't do anything about that.

The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it's not whether they prefer Python or Java. It's whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless. By writing clear technical documentation for end users, they allow people to figure out what their code is supposed to do, which is the only way those users can see the value in their code. There's a lot of wonderful, useful code buried on sourceforge somewhere that nobody uses because it was created by programmers who don't write very well (or don't write at all), and so nobody knows what they've done and their brilliant code languishes.

I won't hire a programmer unless they can write, and write well, in English. If you can write, wherever you get hired, you'll soon find that you're getting asked to write the specifications and that means you're already leveraging your influence and getting noticed by management.

Start a journal or weblog. The more you write, the easier it will be, and the easier it is to write, the more you'll write, in a virtuous circle.

The only way to improve your writing or speaking is to do more writing and speaking. Start small-- blogs and local user groups are great ways to start small-- and most importantly, keep doing it!

posted on Tuesday, April 25, 2006 11:11 AM by jatwood

Comments

# re: Writing, Speaking, and Programming

If you're *really* lucky you'll get promoted to a "working" manager and get to spend all day writing specs. Oh wait, that pretty much sounds like hell *grin*. I agree to a point with Mr. Spolsky, though I seem to be one of the few people that disagree with him more often than not and don't find his products all that great.

He doesn't stress that while you do need well written, human-readable, concise specs and comments they mean nothing if you don't apply that same approach to the actual code itself. One of my favorite points in "Extreme Programming Adventures in C#" is when Ron actually removes a pile of comments because the code becomes self-documenting. That doesn't always work but that is for what you should strive (hmm, that sounds weird trying not to end it in a preposition as proper English dictates).

The core issue isn't how well you can turn a phrase, it's learning the best way to work and communicate within a team and that includes communicating with the developers that will come after you and have to maintain your work. From my many years of experience what managers notice isn't how well you write the spec, it's that you are willing to write it at all since most nerdlings *hate* writing specs. Hmm, actually in a lot of places I've worked the person that has the spotlight is the one whose ideas make sense and approach is clean and functional. Usually either some junior code monkey or a project manager gets the chore of turning three whiteboard's worth of genius into a nice document.

It's funny how he threaded the concept of self-promotion in with communication. Well written technical specs are great but what he really means is if you want the money and the opportunities then you need to create a rep for yourself. It's pretty much all about pimping yourself if you want the big coin. What is sad is that a lot of developers have realized that if you can sell yourself well then you actually don't have to be that great of a coder. I recently worked with a guy that is very well known in VB.NET circles, speaks at conferences, demands high dollar... and his code is a steaming pile.

Of course, all of this assumes that you are actually after, as Mr. Spolsky puts it, "power and influence" as a programmer. Me? I just want to do what I love which is to architect and write code.
Thursday, April 27, 2006 2:14 AM by Shawn Oster

# re: Writing, Speaking, and Programming

Well said.

> One of my favorite points in "Extreme Programming Adventures in C#" is when Ron actually removes a pile of comments because the code becomes self-documenting

So true. I was browsing code yesterday that had this problem. It was designed to be machine readable with extensive nDoc formatted comments, at the cost of making it very difficult for *humans* to read! The irony..

> you are actually after, as Mr. Spolsky puts it, "power and influence" as a programmer

Well, "power and influence" are desirable because that's what it typically takes to get things done, no matter what team you work on. It's not machiavellian (although it can seem that way), it's just a strong desire to get things done.
Thursday, April 27, 2006 4:45 PM by Jeff Atwood

# re: Writing, Speaking, and Programming

I'll take up this advice and start participating more in the blogs here at Vertigo.
Thursday, May 04, 2006 3:38 PM by Alan Le