Majestic Sea Creature

Technical Ramblings from Gregory Brown (@seacreature)

Lessons I've Learned from Writing RBP

Ruby Best Practices is technically my second book. A little over a year ago, Mike Milner and I self-published The Ruport Book as a way to get much needed information out to the community and ensure the project could outlast us. Although I learned a lot by working on that project, and I was proud of what we produced in the end, it’s safe to say that writing a book for O’Reilly on a far more general topic is a whole other ball game.

Over the last several months, I’ve been on a roller coaster ride of emotions when it comes to writing this book. Once the initial excitement died down, I realized what I got myself into, and felt very overwhelmed by the amount of effort it would require to produce a final manuscript. Now that I’m nearing the final stretch when it comes to producing an initial manuscript, it’s safe to say I have a whole different perspective on things.

With RBP not even in final draft form yet, it’s obvious that this post cannot be about how to successfully write a book. Instead, it’s about the things I found that worked for me to keep my spirits high as well as keep me satisfied with what I’ve been writing. Maybe later on, I’ll write a post about what I tried that didn’t work, but for now, I’d like to keep things upbeat.

Have a Vision

Although it’s a nice perk, I didn’t write RBP to become a published O’Reilly author. I wrote it to scratch a giant itch of my own, which seems to be shared among most of my friends. I’ve learned the hard way that this is the only way to keep from getting completely de-motivated about writing when it comes to anything more lengthy than a blog post.

Although in the past I’ve tried to be sure to write content on topics that interest me, I’ll confess that some of my commissioned articles for OnLAMP exist mainly because I had to pay my rent somehow. I could easily pick these articles out from the ones I had my full heart into, and I imagine readers could too. In a similar sense, the Ruport Book was written partly out of a sense of obligation as well, even though it was not financially motivated. Mike and I were always writing the “Ruport Book” for other people much more than we were for us, and that introduced all sorts of challenges that I didn’t want to repeat.

So, I decided with RBP that things would need to be different. The reason why the book exists in the first place is because another publisher tried to recruit me to write a Ruby book for them. I won’t mention them by name, but I will say that they were basically looking for a clone of the Pickaxe that they could slap their brand on, with maybe a little more of a lean towards an advanced audience. I don’t blame them for trying, but I also had no desire at all to write an inferior version of what has already become a cornerstone of the Ruby community.

This is what sparked the idea that eventually became RBP. I responded that I’d be interested in writing a book, but that I want to skip the language introduction and reference components and dive right into immersive exploration of open source Ruby code. I emphasized that I wanted to look at as much code as I could from real Ruby projects rather than just ‘realistic’ examples that always seem to fall short. At the time, I described it like this:

It definitely wouldn't be a reference, it'd be more like "The Second
Book of Ruby", something that anyone who's read one of the popular
language references could use to build their skill set.

After a few days, I heard back from the acquisitions editor who told me that they were interested in my idea, and thought it’d fit the “Problem, Solution, Design” model quite well. Unfortunately, this was about as far from where I wanted to go as you might imagine. This sort of PSD format works fine for cookbooks, but we have enough of those already. I also realized that this sort of writing style was a bit too restrictive for me when I was working on a chapter for Jeremy McAnally’s Ruby In Practice. Though in the end, the content came out fine, I didn’t really enjoy writing it that much and couldn’t see myself heading down that road again.

So I sent my idea to Mike Loukides, in hopes that my history with O’Reilly would help convince them to take the risk on my non-conventional ideas for the book. Here’s an excerpt from the initial conversation we had:

The general idea is for a book titled "The Second Book of Ruby"

Though I had some specific thoughts on this, they're mostly flexible.
The point was that I'd like to write a book that's explicitly *not* a
reference book, but rather shows Ruby in its setting around some real (or
as close to real as possible), fairly advanced projects.

The idea would be that the book would teach people with a technical
understanding of Ruby how to apply their knowledge practically. I'm hoping that the reader could pick up their favorite Ruby reference
and work their way through this book, learning the practical bits that
aren't present in introductory texts.

Mike said he liked the idea and let me roll with it. I didn’t have an outline ready yet, but I put together an unordered list of the topics I wanted to cover, and a few weeks later, we were signing contracts. Except for pushing me to pick a less whimsical name for the book for marketing purposes, they pretty much let me roll with my ideas without any major modifications. I really am thankful that O’Reilly put some trust in me here, because I mostly relied on “trust me, it’ll be good” as a justification for the book’s legitimacy.

I can be honest and say I knew exactly how I wanted RBP to look before I wrote a single word for the manuscript. It’s not that I knew what topics I’d cover in depth or how the individual pieces would come together, but I could visualize every last detail of the qualitative experience that it would become. Armed with this ‘vision’, I felt very motivated, because I knew that although I trusted RBP would be useful to others, I was writing it for myself. This motivation is much greater than any promises of money or recognition could be.

Of course, without counterbalance, this inspiration could turn into a delusional pipe dream. To protect myself and O’Reilly from such a catastrophic mistake, proper checks and balances need to be put in place.

Be Humble and Learn from Others

The best decision I’ve made with this book, hands down, is to assemble my own internal review team. I am lucky enough to have some extremely gifted friends and mentors who know a hell of a lot more about Ruby than I do. I also managed to round up a few folks that are representative of the target audience of this book. With feedback coming from both directions, I feel much more confident that this book actually contains some “Best Practices”.

I’ve encouraged these folks to be candid about their concerns, and they have done exactly that. Reviews are mostly conducted within a google group, where everyone on the review team is welcome to join in the conversations. Sometimes there are some disagreements between the reviewers, and we work together to reach a consensus when that happens. Most of the time, each person who offers commentary gives me ideas from their own unique perspective, and I accept way more requests for revisions than I turn down.

Although the style of the book is distinctly my own, the content itself along with how it is presented tends to be heavily influenced by our reviewers. With each and every chapter going through this gauntlet before it hits roughcuts, I feel much happier with the quality of the stuff that early access readers are getting.

Throughout this process, I’ve discovered where a lot of my weaknesses lie. Rather than waiting until I have most of a final draft in hand (or worse, after publication) to discover where my limitations are, I’ve been doing this iteratively chapter by chapter, thanks to the feedback from our reviewers. By having a few people from the target audience in the mix as the book is developed I also catch issues where I’m glossing over too much fairly quickly.

I’ve been trying my best to treat the book as if it were one of my free software projects. When someone comes along and suggests a way it can be improved, I don’t usually get all up in arms and defend my way of doing things. If a suggestion seems well founded, I just go ahead and fill in the holes as they’re discovered. In the past, I’ve been much more defensive about what I write, but shedding that attitude has been a real win. I’ve had more than one of our reviewers describe our revision process as fun, so that means we must be doing something right.

Make Sure to Start Strong

The first checkpoint of the book called for the completion of any two chapters. Although I could have produced a rough draft of the raw contents needed for these chapters without paying much attention to their overall style, I decided against that approach.

The first two chapters, the one on API design, and the testing chapter, set the standard for the rest of the chapters to come. These took a long time to write, because I wouldn’t let them rest until they matched what I had set out for them in my head. In the end, a pattern emerged that was carried through the rest of the book.

I must admit, it was really tempting to avoid the big picture up front. My instincts told me I should just get something out there first, get the basic examples together and write some prose around them, gluing everything together in a bit of a rough way at first, worrying about transitions, overall flow, and content summaries later. Afterall, this is the workflow that I’ve used for writing articles and blog posts most of my life, and even how the Ruport Book was put together.

Nevertheless, the idea of getting the style and structure of the book set from the get go is something I’ll never regret. The way the book is now laid out, it becomes very clear what will and will not work when forming a new chapter on a different topic. As it turns out, I am far more neurotic than I ever dreamed was possible. Here’s what I discovered after writing my first two chapters:

The initial deep dive into a real project needs to be in depth enough to hint at many of the concepts that will be covered in the chapter, but simple enough to be walked through in a few pages. Each sub-section needed to be relatively self contained, but fit into the overarching theme of the chapter. The book could not at any point turn into a tutorial, and should not attempt to repeat what can be found easily in a reference book. It was important to discuss the context in which each solution was relevant. The answer to whether something is a good idea in Ruby is always “It Depends”, and the job of RBP is to describe the “on what” part of this answer. Sections should not exceed a few pages, and should not dominate a chapter. Contrived examples would be used only for simplification purpose, and could not be used without at least a reference to their practical relevance. The book should rely on demonstrable benefits rather than appealing to the aesthetic or idiomatic value of any given technique.

Starting with this high standard and sticking to it set up meaningful constraints to help keep creativity flowing as I continued on the book. Although this list of requirements that I pulled out of the structure of the first two chapters set up a challenging goal to meet, it has been a hugely useful organizational tool. I think if I went too far without establishing an overall pattern for the book to follow, it would have been much harder to come up with content that I could feel happy with at the end of the day when it came to looking at the book as a whole.

The key thing here is that this wasn’t imposed on the initial content, it emerged. Keeping with the software development analogy, my initial work on the two chapters were sort of like exploratory hacking sessions, I was spiking to discover what I didn’t know about the problem space, and to uncover the problems and challenges that would lie ahead. By working on the chapters until I could see the big picture beginning to form, I ended up with an overall design that I’m really happy to work within.

Of course, changes have been made and my initial efforts weren’t flawless by any means. But judging by the fact that the overall framework has pretty much remained intact without feeling strained or painful to work within, I think this was probably the right way to go.

Don’t Be a Poser

Aggressively Challenge Your Work

Be Patient

And Most of All: Have Fun

---

blog.majesticseacreature.com : Home | Archives | Feed