Writing Tips #3: Code first, write later

Warner Onstine — Tue, 19 Jun 2007 19:48:47 -0700

I’m going to share one of the tips that I got from fellow writer Matt Raible. I’m drastically paraphrasing of course as I can’t remember if he gave me this advice in e-mail or chat.

I recommend that you do a project first and then use that project as the basis for the work. It’s much easier. This is what I did with AppFuse and Spring Live/Primer.

I liked this approach and decided to take it with Tapestry 101 with (I feel) good success. I think it was successful on two fronts; first in learning a framework, second in teaching that framework to others.

This is contrasted to deciding what you are going to write about and designing a code example around that. From my perspective this is problematic for several reasons.

What you’re showing isn’t necessarily a “real-world” scenario that a developer would find in their day-to-day activities.
You will discover tips, tricks, and problems that you wouldn’t have run into in a pre-defined task.
Using a project (especially just one or two) throughout a book helps the reader through the Hero’s Journey showing them the way through the tangled forest by building on the knowledge they’ve just used.
Clearly defined problems are easy for reader’s to understand rather than just “Here’s something cool that you could use to do X”.

Currently I do a mix between using a pre-built project and writing on the fly. I know the project I want to build and generally what I want to show with it and then I start coding with a clear (non-book-related) goal in mind. But I don’t generally code all of it at once (as Matt suggested), instead I code the part just before I write the chapter. This helps solidify the ideas that I want to present in the chapter and helps me in my coding as well.

When coding I rely heavily on TDD now and it helps me immensely when I need to go back and try and explain something, I always start with the test. This is something relatively new that I will take with me on future projects (programming and writing).

Writing overall has definitely made me a better programmer as it has allowed me to dig deeper into a language than perhaps I would have if I weren’t writing about it. This in turn has made me a better writer because I am exposed to new ideas that I can share with the reader.

BlackBox : Writing Tips #3: Code first, write later

Writing Tips #3: Code first, write later