BlackBox

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.