Evolution of a Sentence
I haven't had a lot of time to write the past week or two because of Things Going On, although I am in the middle of no less than three articles on varying topics (tech, writing, design).
As I sat there last night, evolving a sentence in my upcoming JavaScript book, I thought I might once again capture myself in the act for your amusement and vicarious thrill. (If nothing else, I like to show people that what looks effortless rarely is. I'm a woman obsessed.) If you're still bored, you can always check out what I did the last time.
Background: The example sentence is the only sentence between a subheading and a code sample so it needs to stand well on its own.
Really bad
The only way to iterate over an array that’s built into JavaScript is the good old
for()loop.
Inner Editor says: Oh my god, could you bury the point any deeper??
Significantly improved with just one change
The good old
for()loop is the only way to iterate over an array built into JavaScript.
Inner Editor says: There, the point is at the beginning. But booooring. And the placement of "built into" is awkward.
Even better
The good old
for()loop is the only built-in way to iterate over an array in JavaScript.
Inner Editor says: Much cleaner, but so very... meh.
In theory, better, but in reality, too choppy
A good old
for()loop is your only choice for iterating over an array.
Inner Editor says: Yes, this is too abrupt .
Let's punch it up
In JavaScript, your choices for iterating come down to this: a good old-fashioned
for()loop, or a fat load of nothin’.
Inner Editor says: Better rhythm and voice... but it's a JavaScript book. Do I really need to start with "In JavaScript"? Get to the point faster, woman!
Try a little harder, this time
When it comes to iterating through an array, your choices come down to this: a good old-fashioned
for()loop, or a fat load of nothin’.
Inner Editor says: OK, we have a winner.
Post-Mortem
Other contextual info: after the code sample I will be warning people away from 2 constructs that look like they could be use for iterating through arrays, but really shouldn't be (for..in and for each..in). (And for the JavaScript-inclined, I'm not talking about forEach() etc., iterators, at this point. Yes, I know they exist.)
Now, I would be a very bad author indeed if I didn't warn you to be wary when applying this kind of transformation to your own writing: not every sentence should be made longer with editing. It's true that it's usually better to take away than to add, as many great authors and artists have pointed out. However, it's equally silly to always remove as to always add, if you ask me. I think the decision should be made only after considering each sentence's purpose.
And in this case, I feel like my changes to rhythm, timing, and delivery are worth it.
Donation Shout-Out
Thanks to Scott Russell, Adam Keys, and Enrique Delgado for throwing me a some bones by clicking that cute and cuddly Share the Love badge. I haven't spent it all in one place! But I did acquire a book on bluegrass guitar pickin' with some of the funds.
Not that I actually have time to play guitar but a girl can dream.
Talk to me!
Do you ever get obsessed with mucking with your sentences like I do? What do you like to do to improve a piece of writing?
General feedback also welcome, as always :)
Great article Amy ... kneading out that aphorism that there's no such thing as good writing, only good re-writing.
Ruthless, relentless and perfectionist. Two of my heroes, Tolkien and Dahl were masters of both - Tolkien used to start over many times, Dahl constantly rewriting, rechecking.
To paraphrase:
"When it comes to great writing, your choices come down to this: good old-fashioned iterating, or a fat load of nothin’."
Thank you Amy for this article, just a question: how long does it take you to write a Javascript book ? (i'm curious )
ps: see you at railsconf :)
The downside of learning to edit your own work so well is that you end up doing it everywhere. I've been known to spend hours re-writing a single email or forum post. After a while it becomes almost impossible to just write a message out once and hit "Submit".
Fascinating process! Thanks! Not sure, but I think "this" should be "these" since choices is plural. Or "choices" should be "choice", and "this" will stay.
Thanks guys. :)
Paul - I hope you're not comparing me to either of those gentleman!
Sandro: A loooong time. And yes, see you there :)
Conrad: Too true. It's a sickness.
Patrick: I think it's OK the way it is because "this" doesn't actually refer to the choices, but the implicit point of time that it's come down to. It sounds right to me. But I wouldn't bet $50 on it, if you know what I mean.
Anyone care to put forth an opinion?
Enjoyed reading your process, thanks for that. I have to tell you though, I'm not too into what you finished with, and I'm only nit picking because you care and realize that this sentence is tremendously important.
If I may ever so humbly suggest an alternative, "Use a basic for() loop to iterate through arrays, it's the only native to Javascript option." I think it's better because as you tried, it gets to the point earlier. Also, the point is conveyed through an active, tip-like, voice, which segways nicely into the next bit of code.
So that's my attempt, but again, I liked the post, just being helpful.
Avi, first let me say that I absolutely welcome constructive criticism :) I just reserve the right to disagree.
I have my reasons for writing the way I do. I like what I read to have personality, and so I try to add personality into what I write. To my mind, reading a giant book is not just about facts, it's about a journey... and journeys that long and otherwise tedious (for loops? please!) need humor. JavaScript may be a fascinating language all on its own, but not that fascinating.
Trust me, though, few sentences in the book are like that. It'd wear everyone out lickety split (including me). It's just that the others ones don't really make interesting blog posts.
Amy, that's an interesting look at your writing process! I know from having read your articles in the past that a fresh, casual voice is a Godsend when reading something techy.
And how long have you been playing guitar? Looks like the C7 is coming along nicely! :)
Jeff, thanks :)
As for the guitar, let's just say I'm proud that I can usually switch from C to G in 5 seconds or less.
Some day I hope to be able to switch cords and sing... at the same time.
...and when you've mastered that, you need to be able to play The 59th Street Bridge Street Song ( or anything by Paul Simon ) and sing at the same time!
Regarding comparisons, a tidbit I picked up from Covey recently was this ( paraphrased ):
Every time you push the boundaries of your patience, you strengthen the emotional muscles. It's all about aspiring to your capability and not being satisfied by your ability.
Paul, I'll buy that for a dollar.
Also, one of my personal favorites:
~ so i'll continue to continue / to pretend / my life / will never end / and flowers never bend / with the rainfall ~
But right now I'm working on "Ridin on That Midnight Train" (the style -- tempo anyway -- as Doc Watson did it).