I will not write about coding. I will not write about coding.
Chapter 3 is Late. With a capital L. It’s 4:39 AM on a Monday morning — the time of the morning when studies show fatigue degrades driving performance to that of a drunk driver. So I’m going to bed.
Dear book readers of the future, I pledge to not write this book while drunk (well, functionally drunk, I suppose, as the cup in front of me contains tea).
Sincerely, Ted
There is a another pledge that I’m trying hard to stick to: to talk about design of code rather than the mechanics of coding. Picking a book format for technical books is tough because there are a lot of Right Ways to do it:
- The how-to book: Let’s try cooking a pie. First, take the tin out of the freezer and put it on the counter. Next, …
- The reference tome: The oven has three settings. Bake, Broil, and Clean, and a temperature dial. Pie crust requires 35 minutes at 350 to reach a golden brown.
- The cookbook: Cooking a Cherry Pie. Ingredients: cheeries, crust, pie tin. Directions: Step 1 – …
- The patterns book (like an abstract cookbook): Pattern #35: Baking disc-shaped objects filled with fruit in a metal casing…
- The Head-First books: (oh god, please make the fish-eye lens stop!)
- The cyberpunk novel: Zer0-t0x ran to the alley where he saw one of the last functioning pay phones in the city. Reaching for his backpack, he pulled out a blue box and some … ok this is really more of a novel than a technical book.
It seems when it gets late I start enumerating things in <li> tags. But those
are the styles as I see them.
I’m trying to write in a style different than the ones above, that blends technical how-to with the types of discussion you’d want to read on a train. Design-focused like a patterns book but without restricting myself to patterns. I’m taking what I believe are the most important topics in web application design and Ruby on Rails and devoting a chapter to each, tackling it from the perspective of someone interested in developing their ability to design good applications rather than just punch out code.
The tough part is that I’m trying to stay away from both code listings (as in “refer to Listing 2-23 for a 50-line XML file embedded in this book”) and code instruction. The former is easy to do, despite making my page-count deadlines more challenging. The latter is really tough because it means I must assume that the reader understands everything going on in the code examples from a syntax and Rails API point of view.
The assuming parts aren’t hard — all of the examples are short, simple and to the point. Plus people are smart. Most technical books probably err on the side of explaining too much of the syntax anyway. The hard part is keeping myself from delving into long syntactical or API-related discussions — something I’d rather let other books do so that The Art of Rails can focus on design issues.
The Art of Rails is a book for Rails developers about designing web applications with the Ruby on Rails framework and style, not a Ruby on Rails API reference. It is funny to me to find that one of the hardest parts of writing is keeping oneself from explaining too much. You’d think filling page after page would be hard, but when you really sit down and start do to it, you realize that there is actually a lot to say. More than can fit coherently in one chapter, or even one book.
So you have to be very careful to pick and choose the right things, and ruthless at deleting portions you’ve written and like, but ultimately detract from the main focus of the book you’re writing. Anyway. I think the Art of Rails is off to a great start. (despite being a bit behind schedule)
And I’m going to bed.