Writing words vs. writing software Matt 25 Jul 2006

46 comments Latest by lisa

I was reading some quotes the other day about the importance of rewriting…

“First drafts are for learning what your novel or story is about.”
-Bernard Malamud

“There is no great writing, only great rewriting.”
-Louis Brandeis

“Books aren’t written - they’re rewritten. Including your own. It is one of the hardest things to accept, especially after the seventh rewrite hasn’t quite done it.”
-Michael Crichton

…and it occurred to me how much these ideas apply to writing software too.

Grinding it out
Whether we’re authoring software or prose, rewriting is key. Rewriting is when you turn good into great. It’s true for books, blog posts, marketing copy, interfaces, code, etc. For all of them, we grind it out. We get something down, share it, get feedback, revise, and then do it over again. We get where we’re going via lots of wrong turns.

Sometimes we even throw everything away and start over from scratch. Yeah, that can be frustrating. But if you never throw anything away, you’re holding on to your worst ideas.

Writing copy
For a short blurb, we just bang it out and move on. But when we want to do it right (e.g. when writing Getting Real, the Job Board info page, or posts like this), we go through a cycle of tweaking and revising. Here’s how the process works:

  1. Idea.
  2. Write a version.
  3. Get feedback from rest of team. People offer suggestions, post related images, and tell you if something sucks. Sample comment: “Here’s another angle. not sure if it works or not, but I’ll freestyle it…”
  4. Rewrite. We’ll often bring ideas into Writeboard at this stage in order to collaborate on edits.
  5. Go back to step 3, if necessary.
  6. Publish.
  7. Get more feedback, this time from outside audience.
  8. Tweak again, if necessary.

Writing software
It’s actually the same way we create software. There’s a lightbulb moment. Then sketches. An interface is built and passed around (seeing a real screen makes all the difference in the world). Feedback pours in. Revisions are made. (Sometimes entire ideas are scrapped and we go back to the drawing board.) Something gets built. People start using it and make comments. More tweaks. Launch. Listen to outside comments. Repeat the process.

One important part of all this: You can’t fall in love with your baby. You need to realize your work is going to get twisted up and turned inside out. It’s better to get that over with sooner than later. If not, you risk falling head-over-heels for your creation only to have your heart broken later. So share stuff early and often.

More words/software overlap
Rewriting isn’t the only similarity between how we author words and software…

“Of every hundred people who start a novel, only three finish.” (source)

woodyA similar ratio probably applies to software entrepreneurs. Everyone and his cousin is working on a web app. But how many are actually finishing? That’s why we argue for biting off less. Write a short story/small app instead of a novel/massive app. Shrinking scope means you actually finish. And finishing is huge. When you finish something, you show up. And, like Woody Allen said, “Eighty percent of success is showing up.”

“The worst thing you write is better than the best thing you didn’t write.” (source)

Writer’s block haunts writers of all stripes. Blank pages, whether on the web or on a piece of paper, are the enemy. Author Victory Crayne offers fiction writers advice that’s good for designers and programmers too: “Turn off the editor in your head and just bang some words. The best cure for writers block is to write. Anything.” We’re big fans of the brain dump. Get something down: words, sketches, whatever. Get the snowball rolling.

“Remember this: Don’t spend too much time visiting writing groups. You are not writing then. You are writing when you are WRITING.” (source)

Dig that last line. It’s easy to get caught up in the hubbub surrounding software instead of actually making it. You can spend all day reading guru blogs, listening to podcasts, going to networking events, etc. That’s not writing. Writing is writing. That’s where the alone time zone can come in handy. Sometimes you need to shut yourself off from the outside world and just get shit done.

“Editing is the most difficult phase of writing — and it is also the most crucial.” (source)

We’ve talked before about how we’re editors: “The editing process is what makes a great product. Editing the feature list, editing customer requests, editing the interface, editing the code, editing the marketing, editing the copywriting. It’s not about designing or writing or coding, it’s about trimming those weeds back before they ruin the lawn.”

For example, this post once had about twice as many words. Now it doesn’t.

“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 sentences short, or avoid all detail and treat subjects only in outline, but that every word tell.” (source)

It’s a quote we mention early on in Getting Real because it’s so appropriate. Vigorous writing of words is the same as vigorous writing of software. Every word, every line of code, every interface element should tell.

46 comments so far (Jump to latest)

Simpleton 25 Jul 06

Regarding the “Vigorous writing…” quote, I had a tough time reading it because of the lack of “extra” words… I spent more time on the last sentence trying to figure out exactly what it means than I would have if it read a little more “modern.” It definitely feels a little “older” in style. Maybe consise != clarity all the time?

Brandon 25 Jul 06

Wow, this is one of the more insightful posts I’ve read on SvN. This is why I subscribe to your feed.

Great post - keep it up guys.

Justin D-Z 25 Jul 06

Or, Refactoring by Martin Fowler.

Carlos 25 Jul 06

Reminds me of the scene from the movie “Amadeus” when the King (?) thinks there are “too many notes” in Mozart’s latest piece. Mozart replies there are precisely as many notes as he needs. :)

David Benton 25 Jul 06

Hmm, that’s funny. Michael Crichton’s books always feel hastily thrown together.

sean 25 Jul 06

well, of course, this is dead-on. there are a million examples of writers who have learned the importance of precision and accuracy in writing, and who can provide great quotes about it. hemingway’s sparse style was developed in part as a way to get around having people edit (read: censor) his stories. he stripped them down so that each word was critical, as with mozart’s notes comment. that way, he knew that he could stand by each word if challenged, and prove that each word was critical to the meaning of the story. mailer, kundera, gardner and many more, each offer similar wonderful insight about writing. that these methods can be applied to source writing is only natural. but as all writers know, the most natural things arent always obvious. which is why we’re grateful to come across insights such as this post. thanks.

Phil 25 Jul 06

Just as apt from the Amadeus movie is the scene where Mozart’s patron asks where the composition is. Mozart points to his head and says the piece is, “up here.”

The reply (paraphrased): “It doesn’t do anyone any good up there. You have to write it down!”

Ben Edwards 25 Jul 06

This is a great post and something to keep in mind at all times, in many, many endeavors. Great work, as usual!

Earl 25 Jul 06

Enjoyed it (vigorous comment)! ;-)

Matt 25 Jul 06

Or if you subscribe to the drug induced philosophies of “Naked Lunch”:

“See, you can’t rewrite, ‘cause to rewrite is to deceive and lie, and you betray your own thoughts. To rethink the flow and the rhythm, the tumbling out of the words, is a betrayal, and it’s a sin, Martin, it’s a sin.”

Just Some Guy 25 Jul 06

“It’s easy to get caught up in the hubbub surrounding software instead of actually making it. You can spend all day reading guru blogs, listening to podcasts, going to networking events, etc. That’s not writing. Writing is writing.”

You’re talking about software, though. Writing code makes you a better programmer. It doesn’t help you see how to make an interface better, a task flow smoother, or an interaction more understandable.

A more apt comparison would be between designers and writers. The only way to get better at design is to design.

Leah 25 Jul 06

Ah, I subscribe to S v N… I don’t know why, something about it speaks to me—even though I’m not a programmer or a first adopter to technology. I’m a bit of a luddite, but don’t tell my boss.

But as a writer, this post is getting printed out and hung up in my cube. Thanks for the unexpected words of wisdom.

Cameron Booth 25 Jul 06

For some reason, this reminds me of the story I heard back in design class - an ancient chinese emperor hires the best painter in the land to make him a painting of a fish. It takes months..and each month the emperor asks “When’s my painting coming” and the painter replies “It’s not ready yet”.

Finally after years of waiting, the emperor gets upset and travels to the painter’s studio, demanding to see the final piece. Right in front of him, the painter pulls out a pen, some ink, and a sheet of paper, and in a couple swift strokes paints the most beautiful fish the emperor has ever seen.

“If you just did that now, why did it take months!”, screamed the emperor. Silently the painter opens the door to his studio, and thousands upon thousands of not quite perfect fish paintings fall out.

It’s a process…..it takes a lot of wrong to get to right.

Rahul 25 Jul 06

I agree, this is one of your best posts in quite a while. We need more like this and less comments collections and random web links! (though keep the UI shots, those are great)

Ryan Tomayko 25 Jul 06

It would be interesting to hear your thoughts on striking a balance between “release early/often” as described here with a somewhat different philosophy David had me thinking hard about a few months after the initial Rails release. We had a short debate on IRC arguing the virtues of “release early/often” vs. “release no sooner than you are certain the core concepts are evident.” This seems to play heavily into the ideas behind “opinionated software” (e.g. you can’t very well be opinionated if the project hasn’t matured to the point of forming any).

I believe we got on the topic through discussing the (now defunct?) Subway project — a Railsalike in Python. It was in very early stages of development but there was a decent number of people already participating on the mailing list. David’s prediction was that the project would be taken in wildly different directions and end up lacking simplicity and coherence (i.e. “beauty” :) due to the large number of contributors and a widening vision. In retrospect, it seems to have done *exactly* that.

What I took away from David’s POV was that it can be dangerous to release a project too early because you run the chance of attracting the wrong community / feature contributions and that too many cooks in the kitchen too early can derail a project that may otherwise have been successful given a more defined vision and set of opinions. A strong maintainer can relieve many of the issues with releasing early but keeping the crack out of a project can become a full time job, especially at the early stages.

There’s a period of months in the loudthinking archives with David talking about this new web framework thingy he was working on but not making it available in any form. I wonder if you consider early Rails development as following the precepts you’ve described in this post or whether it was more conservative in its approach?

Bob Aman 25 Jul 06

Awesome, glad you agree. Perhaps a rewrite of ActiveSupport is in order?

Check this out:

require 'rubygems'
require 'feed_tools'
FeedTools::VERSION

-cries-

ActiveSupport is just broken and wrong.

Andy Brudtkuhl 25 Jul 06

best post on svn in quite sometime. excellent points.

critic 25 Jul 06

Is Crighton admitting to writing the same book over and over with different titles?

Robin 25 Jul 06

Has Brooks put it in Mythical Man Month, “plan to throw one away”.

Robin 25 Jul 06

As Brooks put it in Mythical Man Month, “plan to throw one away”.

(see, that that was a demonstration ;)

andrew 25 Jul 06

Love it.

Cory Doctorow offered a basic algorithm for first-pass refactoring:

bq. Here’s a procedure that I almost always find useful for improving almost any kind of written composition — a speech, an essay, an op-ed or a story. As a first pass, try cutting the first 10 percent (the “throat clearing”) then moving the last 30 percent (the payoff) to the beginning of the talk (don’t bury your lede!). About 90 percent of the time when someone gives me a paper for review, I find that it can be improved through this algorithm.

Link here.

Greg Von Dare 25 Jul 06

OK, this is good advice; really. But rather late in the timeline to count for much. We’ve known what makes writing good for centuries and every generation does not need to discover it anew. A quick dip into “Elements of Style” is more focused, informative and rewarding than this admittedly casual and ad hoc blog. The rigid semantics, lack of context and the immense stupidity of the interpreter makes code a poor analog for creative writing. On second thought, I’m bothered by the comparison at all.

DHH 25 Jul 06

Ryan, I consider the way Rails has been managed an implementation of these philosophies. Rails was used and horned and rewritten many times within the confines of 37signals before being released. The particulars of Basecamp pushed back on the framework design, Jason and Ryan pushed back as designers consuming the views.

I see this mostly as a call for you to be your own editor in stage two. Get something real written. Get an application going (stage 1), then become an editor and extract commonalities (stage 2).

Regarding Subway and how many cooks cause malice, see also Jason’s post on Most businesses self destruct. That’s at least as true of open source projects.

Tony 25 Jul 06

As I almost always do when you guys post about writing, I’m going to recommend that everyone read On Writing Well. Sure, it will take you longer than reading Strunk & White, but it is a great book and will definitely improve your writing (and perhaps coding by extension?).

David Weiss 25 Jul 06

There’s a reason in the writing world there is only one editor, or one or two copy editors. If you’ve ever been in a group code review, you’ll know why too.

David Weiss 25 Jul 06

There’s a reason in the writing world there is only one editor, or one or two copy editors. If you’ve ever been in a group code review, you’ll know why too.

Brooks Jordan 26 Jul 06

That’s a damn fine post, Matt.

Chris Clark 26 Jul 06

Vigorous writing of words is the same as vigorous writing of software. Every word, every line of code, every interface element should tell.

Funny, I was always told that the first rule of great fiction is that is should show, not tell.

Chris 26 Jul 06

I’ve blogged frequently for the past two years. It’s been a perfect outlet to keep me writing at some level after leaving college (and no longer getting to take English and creative writing classes).

About a year ago, I started to learn HTML and CSS, which I understand aren’t necessarily intense programming codes when compared to any of the other back-end types. But their structure and logic appealed to me, and I was amazed at how easy it was to pick up and build on what I had learned.

Have limited experience with both coding and creative writing, I’ve found some obvious similarities and differences. It is good to do both consistently to remember the structure.

The difference comes, for me, with creative writing. I need to keep up with it to keep my sense of pace, flow, etc. All that stuff you can’t really measure.

I’ve enjoyed both tremendously, though. Wish I could make a career out of it!!! For the moment I’ll be blogging for enjoymenat at Yugflog.com

Karan 26 Jul 06

Good article, but I’d second Chris Clark just above - the rule of writing is show, don’t tell =)

Kharen 26 Jul 06

Fantastic! Thank you very much for that.

Now I know why I have the “urge” to write prose, fiction, etc. I have been writing software for quite a while. And now I’ve been bitten by the “word writing bug”.

I love how you’ve shown, proven the similarities between writing words and software. I totally agree they are the same, too much so … it’s scary!

Also agree that writing a success is more about rewriting and getting comments. Feedback is always useful. We should never under value its importance.

Would also like to take this opp to say “Kudos to your work on Wordpress”. Maybe I should suggest to my boss that our job title be changed to “Professional Bug Creator”. LOL.

Cheers!

Shirley Buxton 26 Jul 06

Matt, this is a great post. I cannot tell you how many copies of The Elements of Style I have given away.

(I have a self-published book, Link to Excellence, which shipped from the printers today. Yes! :))

Blessings,

Shirley Buxton
www.writenow.wordpress.com

rayray 27 Jul 06

mise59@yahoo.com

nursegirl 27 Jul 06

@Karan, @Chris Clark:
The vast majority of writing in this world is not fiction…

protected static 27 Jul 06

nursegirl - even non-fiction should probably show instead of tell. And yes, I’m including software in that category.

That said, there are times and places for telling - right here, for instance: I’m telling you my opinion. Instruction manuals should also ‘tell’ when appropriate, but I’m willing to bet that the use of ‘show’ more than ‘tell’ makes for a better manual.

Or this could simply point out the problem with absolutes. In all things seek balance, yadda yadda.

Deirdre Saoirse Moen 27 Jul 06

“The essence of writing is rewriting.” — William Zinsser

Iram 27 Jul 06

hehehe, that last bit reminded me of the 45 min. scripts we would have to write for Mr. Roman only to cut them back to 13 min. scripts in the end :-)

Scott Mackenzie 30 Jul 06

One of the most insightful posts I’ve read in a long time. Thanks so much!

It’s similar to the attitude I try to follow… just do it! Quit talking about it.

sosco 01 Aug 06

I’ve blogged frequently for the past two years. It’s been a perfect outlet to keep me writing at some level after leaving college (and no longer getting to take English and creative writing classes).
I cannot tell you how many copies of The Elements of Style I have given away.

sosco 01 Aug 06

I’ve blogged frequently for the past two years. It’s been a perfect outlet to keep me writing at some level after leaving college (and no longer getting to take English and creative writing classes).
I cannot tell you how many copies of The Elements of Style I have given away.

Jason 08 Aug 06

The first comment on this entry, by Simpleton expanded on the joke I found in the quote.

The quote DOESN’T contain just the right amount of words. It droped a few here and there and caused the reader to stumble.

stephanie 20 Sep 06

Hi my name is stephanie I like to write because writing is good because sometimes peopel read some books they can lrean things from the book because they give you clues that’s how to lrean to write tha’s how you read a stroy in that’s what I like to do.

stephanie 20 Sep 06

Hi my name is stephanie I like to write because writing is good because sometimes peopel read some books they can lrean things from the book because they give you clues that’s how to lrean to write tha’s how you read a stroy in that’s what I like to do.

stephanie 20 Sep 06

Hi my name is stephanie I like to write because writing is good because sometimes peopel read some books they can lrean things from the book because they give you clues that’s how to lrean to write tha’s how you read a stroy in that’s what I like to do.

stephanie 20 Sep 06

I won’t to be a model when I’m big to be a model that’s wath I like to do when I’m big I’m going to be the greats model.

lisa 11 Oct 06

But stephanie, I think you’re not learning the right way to spell or talk. Sorry.

How old are you?

Post a comment

(Basic HTML is allowed)

NOTE: We'd rather not moderate, but off-topic, blatantly inflammatory, or otherwise inappropriate or vapid comments may be removed. Repeat offenders will be banned from commenting. Let's add value. Thank you.