I'm currently working with Greg Wilson on The Architecture of Open Source Applications. It's a collection of essays written by open source coders about the architecture of their projects. I'm mainly the format monkey, but sometimes Greg lets me out of my cage to do some editing. Last week he set me loose on a chapter which had some problems with structure to see if I could come up with some helpful comments for the author.

I knew the chapter bothered me, and to begin with I could specifically point to one problem: the author didn't introduce the subject of the chapter until the fifth paragraph of the second section. (He'd been talking about and around the subject until then, but never overtly linked it to what he was saying.) Apart from that I didn't have anything specific and helpful to say.

Also I didn't know what to do next.

Don't tell anyone this, but I'm not really an editor. Okay, I'm an "editor" in the same sense that I'm a writer: I edit. But I'm not, say, seasoned. Experienced. I'm new to this. So I didn't know how to approach this chapter. I tried a few things.

First I read it again. (Of course further complicating matters was the fact that the topic of the chapter is not something I was familiar with, so not only was I editing the chapter, I was simultaneously learning from it. 1) Reading it again helped me understand the subject better but I still didn't know what I needed to say to help the author make the chapter better.

Next I wrote out an outline of the chapter, to try and see the overall structure. That helped me see that the author never clearly stated the problem he and his team were solving. But I felt like the outline was too static — I wanted to be able to move things around.

So I printed out the chapter and cut it up into sections, taped together along page breaks. That was mildly diverting and passed a lot of time, but in the end all I really got was a lot of awkwardly-sized bits of paper. I couldn't do much with the bits of paper, but the act of fabricating them helped me break the chapter up into blocks, mentally. 2

After all that I finally had a few suggestions, although ironically not so much on the structure of the chapter — that's mostly fine. The problem is that the author spends a lot of time providing unnecessary details and elaborations, while leaving out the "obvious" (to him) fundamentals that people who don't work with his subject will need to know to understand the chapter. 3

What I ended up doing was rewriting the first section to clean it up and make it into an actual introduction, and asking the author to introduce some other topics more effectively (and gently) later on in the chapter. I hope I will get a chance to tighten up some of the language and take out excess material later in the editing process.

The whole process was fun but also made me very uncomfortable. As I was doing all that outlining, cutting, pasting, researching and thinking I felt insecure and kind of dumb. "Is this what I'm supposed to be doing? Is this going to work? Am I wasting time? Should I do something different?" I hate doing things I don't already know how to do, and I had to keep reminding myself that this is how you learn — you flail, you try things, you screw up, you try other things, you get better. It does take time and it does make you feel stupid, but then after it's over you know a little bit more.

(Note to Greg: I didn't bill you for most of this arduous process. The only thing worse (for me) than not knowing what I'm doing is not knowing what I'm doing on someone else's dollar.)

  1. After bashing my head against the chapter for an embarrassing amount of time I finally looked some stuff up in Wikipedia to get a better feel for the subject matter and terminology. Lesson 1: Consult other reference material if you are out of your depth in the subject matter. 

  2. Rather than chop the actual chapter into pieces, next time I think I will turn to every author's friend, the Index Card. Summarizing each section onto an index card will force me to understand the material, and the cards themselves are much easier to handle. 

  3. Next time I read a chapter for the first time, I will make a note of every time I say "Huh?" or have a question while I'm reading. My Loyal Readers should not be saying "Huh?"