Dear Author

In my role as technical editor for and as a reviewer for my trusted colleagues, I have the opportunity to read drafts of articles and some books. I see some troublesome behavior. I know it because I exhibit it. In all cases, the author receives feedback the author doesn’t like, but doesn’t want to stop writing.

In my role as technical editor for the AgileConnection and as a reviewer for my trusted colleagues, I have the opportunity to read drafts of articles and some books. I see some troublesome behavior. I know it because I exhibit it. In all cases, the author receives feedback the author doesn’t like, but doesn’t want to stop writing.

Decide on One Idea

I am the prime example of this one, so I will use an example from my writing. I was trying to write one of my Pragmatic Manager emails last week. I sent it to Esther. It was only about 200 words. She counted the number of ideas, in the opening story of fewer than 60 words and stopped at 9 ideas. She could not read anymore.

“JR, what is the main idea of this piece?”

I just about fell out of my chair laughing at myself.

I read this in articles and chapters all the time. You need one main idea in an article or a chapter. When you are done with that idea, it’s time for another article or a chapter.

If you have lots of ideas, it’s fine to have another article or a chapter. When I write books, I have a file called, “Stuff-to-put-somewhere”. It’s ideas I can’t use now, but might have a chance to use later. Maybe you don’t need a file like that, but you need a place to put stuff you are not going to use now.

You do not need to put everything you know into this article or this book. Really. I promise you.

BTW, Joyce Statz was the first one to give me this advice on my very first paper in 1995. Joyce, I am still learning. Esther gave me this advice last week. BTW, when I see this with authors, I ask them questions, as Esther did with me to help them see which ideas they want to address, or how they want to rewrite the piece.

Boring Writing Stays Boring Until You Change Something

Unless I know you well I don’t tell you your writing is boring. I may tell you that you need a story. Or, I might tell you the writing is dry. Or, that you need a story. Or that I need an example. But, a story with people yelling at each other or working through a project is a great idea.

If I tell you need a story, believe, me. You need a story or an example. I don’t tell you that because I want to hurt your feelings. I’m telling you because I fell asleep reading your work. At 8am. After I woke up and worked out. Or, took a shower. I gave your writing the best shot I knew how. It put me to sleep.

If I tell you your writing is boring, you have several choices:

  1. You can insert a story;
  2. You can take a different perspective on the entire article;
  3. Put the piece down for a week or two and come back to it later.

When Esther and I wrote Behind Closed Doors, Jerry gave us feedback on our first draft and told us it was boring. We rewrote the entire book. He told us our second draft was more boring! Esther is the one who had the transforming idea that we should write the story of Sam the perfect manager and pull out the lessons after we told the story, and that we should pair-write the book.

Do not write more words. Please. Unless you change something. If you write more words in a piece that’s already boring, it will become more boring. If you take words out, it might become less boring. Maybe. No guarantees.

90% Done Is Not Close

You are convinced you are within a few hours of finishing the piece. This is just like a software project. You are not. You are days or weeks or months away from finishing that piece in this form.

Writing in a natural language is not so different from writing code. When authors tell me they can’t take the time to put in a story because they are “almost done,” I know the piece is going to stink. I know I am going to iterate forever trying to get a great piece of writing from the author.

Throw it out and start over. It will be faster.

Sunk Cost Grabs You Every Time

When I suggest to an author that he or she try another approach, or read the piece out loud or redo a picture in a new tool or even write in a new tool, and the author rejects my advice because “I’m almost done and it’s so close,” I know the author is thinking of the sunk cost in the project already. I see this with books more often than with articles.

I want to shake the author. “Author,” I want to say, “Do you want a great article? Or do you want a crappy article? Because what you have right now stinks. Do you think I am suggesting this to you because I want to make you crazy? No. I am suggesting this to you because what you have right now is not worth publishing. I am going to go around this article with you 1700 more times and we will still be working on this graphic from now until doomsday.” I don’t say that. What I have said is, “PowerPoint is not a good tool for graphics.”

Too many authors get stuck in their thinking because of their tools. Do not write a book in Word. Do not develop graphics in PowerPoint. Those tools will constrain your thinking for the book and the graphics. If you think of them as tools for an initial rough draft of two or three pages or two or three drawings, that’s fine. But they get in the way for really writing.

For those of you who are writing books, I suggest either TextMate with leanpub or Scrivener. I much prefer TextMate with leanpub. You will need to rearchitect your book at least 6-7 times. That is, you will need to take large chunks of words and move them from here to there. If you don’t, your book will become more boring. You want to keep each chapter in a separate file. Word does not work that well for books. Oh, like any other tool, you can make it work.

(Yes, yes, I know some of you have succeeded using Word to write your books. Fine. You are the exceptions who prove the rule. If you want me to review your book, use leanpub.)

Passive Voice Stops Your Writing Dead

When I read passive voice, I question it. Not because I am a copyeditor. But because I can’t tell who is talking. Who is doing the work? Who is talking?

Search for passive voice and excise it. I just discovered a passive voice bundle for TextMate and installed it. I am one happy woman.

Noun-Verb Phrases are For the Birds

Noun verbs or noun-verb phrases are two-word verbs or phrases such as: “set up” instead of arrange, “get rid of” instead of eliminate. They weaken your writing and make me wonder what the heck you mean.

If you are wondering what “for the birds” means, it’s an idiom that means useless. That’s what those noun-verb phrase idioms are. Useless.

Use them for your first drafts. Then find them and replace them with strong verbs. Think of them like adverbs.

Excise Adverbs

If I see the word “basically” one more time, I might have to vomit. Or actually. Or, firstly. Firstly? Come on. Make a numbered list if you must.

It’s okay to write the adverbs when you write. In your first editing pass, remove all the adverbs. See how much stronger your writing is? Love it.

You might think, “Oh, did I say that? Wow, that’s really strong.” See what happens when you eliminate the adverb? You become powerful. Your writing becomes powerful. You tower over the world. You, too, become seven feet tall. I recommend it. Honestly. (Yes, that was a punny adverb. Are you paying attention? :-) Why do you think people are so surprised when they meet me in person? I have everyone convinced I am seven feet tall. Including me.

You are writing an Article or Book of lists instead of prose.

I like to read. Reading to me means I will read paragraphs of prose for a few pages. I like stories to interrupt my prose. Maybe a picture or two. I like sidebars, tips, and warnings to interrupt my prose. Those interruptions are fine.

A list is good, if and only if it pulls ideas together.

I do not like books of lists. I do not like articles of lists. When I attempt to read them, I wonder, “Did this author try to turn the slides into this book or article? I bet this was slide 32 and this was slide 33.”

If you have slides and want to turn them into a book, you are better off talking them first, and transcribing the talk. Make the slides a conversation with the reader.

I can read your two-by-two matrix. I have mine, you can have yours. I can read your lists, I certainly have mine. But don’t make me read an entire article of lists. I need prose to knit it together.

Larry Constantine gave me the best advice years ago when he asked me to write an article for the last page of Software Development magazine. “No lists, Johanna. One article of all prose.” Oh my goodness. I don’t think I had ever done that before. Well, I did.

Larry is writing some terrific fiction these days, under the pen name Lior Samson. Read it. That’s an order.

Writers Make Mistakes, That’s Why We Have Editors

I make these mistakes, too. Do you think I’m perfect? Oh no. Not by a long shot. I make all these mistakes. That’s why I recognize them so well in other people’s writing.

If you want to be a better writer, read Jerry’s writing book, Weinberg on Writing: The Fieldstone Method. I have the paper version. Start here with links to the electronic versions. I also like Stephen King’s On Writing. I read the 2000 version.

Want to Write for the Agile Journal?

After all this, if you want to write for the Agile Journal, you know what you will get. I will challenge you to be the best writer you can. I will challenge me to be the best editor for you. Together, we will partner to create a great online experience for our readers.

I won’t copyedit you. Unless I can’t stand it. If you adverb me to death, I might say something. If you passive voice me, I might say something, because I will be confused. I might be a pain in your tush. But you will exit the experience with an article you can be proud of. And a new friend. Me.

And, if you are wondering how long it took me to write this, I don’t know. But I started writing it a few days ago, and WordPress tells me it went through 8 revisions. I’m sure there area mistakes even though I have self-edited.

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.