Writing A book Is Like Developing Software

I'm in the process of writing my upcoming book: The Art Of Unit Testing, and it's proving to be a big challenge. Bigger than I imagined. (Here's the first sample chapter - PDF)

Book == Software Development. The Comparison might seem a bit weird at first, but my experience so far seems to be compatible with this.

Some examples:

  • Creating the Table Of Contents == Big Design Up Front

When submitting your book proposal to your publisher(I work with Manning on this book), they'll ask you to provide a TOC for the book including chapter length, sub sections in each chapter etc. Whatever you write there is at best a guess.

As I wrote the first 2 chapters of the book I realized that the TOC I had was all wrong, and that I was doing it all wrong. So I rewrote the TOC because I suddenly realized that half the subject I wanted to talk about in the last half of the book, actually belong in the first few chapters, and that 3 chapters from the rest can be combined, and that some of the stuff I wrote is simply not going to be relevant, as a specific chapter, that is.

Kinda like design, where you realize you designed something wrong the minute you try to implement the design.

  • You learn as you go

Like software, you realize what you actually want to say in the book as you are writing it, so the design needs to keep changing, and your thoughts about what's good and what's not keep changing as well.

  • It's always more complicated than you initially thought

Nothing to add here.

 

Have you ever written a book? Feel the same way?

Published Tuesday, March 13, 2007 3:12 AM by RoyOsherove

Comments

Tuesday, March 13, 2007 6:44 AM by Dave Bartlett

# re: Writing A book Is Like Developing Software

Thanks... enjoyed reading your first chapter - looking forward to more!

Tuesday, March 13, 2007 8:44 AM by Aaron

# re: Writing A book Is Like Developing Software

Just last night I had that same thought! Well, mine was just related to writing an article for my blog.

I often feel like both code and writing (any creative task?) would be so much easier if only I could work out what I was trying to do up front. Unfortunately, it never seems to be possible - the requirements aren't something that seem to exist beforehand - they get generated or modified as development or writing progresses. Or is it just a lack of a disciplined approach ?

Tuesday, March 13, 2007 9:20 AM by Mickey Gousset

# re: Writing A book Is Like Developing Software

That's pretty much how I felt when writing Professional Team Foundation Server.  Good Luck!  Shoot me an email if you need a tech editor.

Tuesday, March 13, 2007 10:35 AM by Liming

# re: Writing A book Is Like Developing Software

I loved the fact you talked about integration tests. It's a confusing topic that people tends to mix with unit tests.

Looking forward to reading your book.

Tuesday, March 13, 2007 10:52 AM by Josh Adams

# re: Writing A book Is Like Developing Software

I would agree with the comparison between writing and software development.  In classic books about good writing like William Zinsser's "On Writing Well" the point is made that good writing means continually modifying and editing pages, paragraphs, and sentences over and over again till you get it right.  With each iteration of changes you try to simply your language and remove excess words--which results in powerful, easy-to-understand, quality writing.  

Basically it's just refactoring.

The other interesting thing is that people like Zinsser constantly bemoan all the example of terrible writing that are ubiquitous today: lots of business blather that says nothing.  The classic example is the word "utilize".  It's longer and sounds more sophisticaed than "use" but adds ZERO meaning in most cases. Obviously it's the same with code.

To me "software development as writing" is a better paradigm than the more traditional ones like "software development as construction" or "software development as gardening".

Tuesday, March 13, 2007 12:05 PM by Daniel Moth

# re: Writing A book Is Like Developing Software

You are right on the money 100%. All we need now is to find a publisher that agrees and see if we can change the process of writing books :)

(btw mine is out soon and it was much harder than what I initially thought... keep the faith!)

Tuesday, March 13, 2007 12:34 PM by Jason Bock

# re: Writing A book Is Like Developing Software

I wrote a diary as I was writing my CIL book. You can find it here:

http://www.jasonbock.net/JB/DiaryCil.zip

Take it FWIW :)

Tuesday, March 13, 2007 1:26 PM by Dee

# re: Writing A book Is Like Developing Software

Book writing obviously has been around long before programming.  It seems odd you would make a reverse comparison....

Programming is like writing a book.

Tuesday, March 13, 2007 2:22 PM by Jeff

# re: Writing A book Is Like Developing Software

I didn't find the process to be all that similar (my book: http://www.amazon.com/exec/obidos/asin/0321294475/coasterbuzz-20). Working with A-W was more of a "big bang" delivery process than one of iterations. The editorial review process was a little like a code review though.

Tuesday, March 13, 2007 3:15 PM by James Higginbotham

# re: Writing A book Is Like Developing Software

Same here for the book I wrote in '96 with Jeff. Much time was spent on the TOC that we wanted to change up but it was too late. It is very much a waterfall process in terms of working with publishers, but an iterative process when writing. I learned my lesson.

I'm now focusing more on ebooks, with my first one on volunteer leadership coming out soon. I must have changed the outline about 5 times before I got the reader experience right.

Tuesday, March 13, 2007 6:20 PM by Fabrice Marguerie

# re: Writing A book Is Like Developing Software

Jeff, James, I guess that the experience can vary depending on the publisher.

See my own experience: http://linqinaction.net/blogs/main/archive/2007/03/13/my-writing-experience.aspx

Tuesday, March 13, 2007 6:56 PM by Brendan

# re: Writing A book Is Like Developing Software

I've found that too. You start off with broad parameters, then the development/drafting is a process of refinement and refactoring.

The main difference between them (to my mind) is whether a book release 'works' or not - more of a subjective test metric that an objective one!

Wednesday, March 14, 2007 12:20 AM by Bob Grommes

# re: Writing A book Is Like Developing Software

Oh, I most definitely agree re starting with a good table of contents.  I was primary author of a couple of development books for NewRiders Press back in the early 90's ("Inside FoxPro for DOS" and "Inside FoxPro for Windows" -- I'm dating myself here).  The publisher offered me the project based on what they termed the "lucidity" of my postings to a MSFT beta forum they were lurking on.  But I initially turned it down because the Table of Contents / outline sucked.  They said in effect, "well fine ... let's see YOUR outline" ... and the rest is history.

If you can't construct a book outline / TOC you probably can't write decent software.  You have to know where you're going ... as you point out you'll refine it as you go but you can't just plow in and write what pops into your head ... you'll end up with a rambling, and possibly incoherent, book.

Wednesday, March 14, 2007 5:57 AM by Fabrice Marguerie

# re: Writing A book Is Like Developing Software

It would be interesting to find out how to do TDW (Test-Driven Writing) ;-)

Wednesday, March 14, 2007 12:23 PM by James Higginbotham

# re: Writing A book Is Like Developing Software

Fabrice,

I totally agree - Jeff Schneider and I had Que as a publisher, who in '96 and '97 were going through some internal transitions that impacted the success of the book.

The lesson: pick your publisher carefully!

I've heard great things about Manning, even in the early days. Duane Fields, Mark Kolb, and I compared notes on the two publishers and they were worlds apart. I would consider writing another book, but it would have to be the right publisher first.

Friday, March 16, 2007 5:57 AM by Arnon Rotem-Gal-Oz

# re: Writing A book Is Like Developing Software

It was comforting to see that others share the same problems :)

I just spent a couple of months "remodeling" chapter 1 and "refactoting" chapter 2 before (finally) going back to writing new chapters