Writing books is hard. I used to think it was a lot like writing a blog, only scaled up a bit. But it's much more involved than that. Once you're a published author, suddenly you have obligations and responsibilities to your publisher, and to the paying, reading public. The ante has been well and truly upped.
A few years ago I wrote a slim volume - Test-driven infrastructure with Chef. At the time I wrote it, I was pretty much the only person trying to do infrastructure code in a fashion inspired by the TDD and BDD schools of thought which I practiced as a software developer. When it was published, it was remarkably popular, and despite really being a book about test-driven development, and infrastructure code, it was widely read as a book 'about' Chef.
The problem was, this was the only published book on Chef. Chef as a tool was growing in popularity, and regular complaints were heard about the quality of the public documentation on the Opscode wiki, and about the failure of my volume to be a comprehensive introduction to Chef. Notwithstanding the observation that my first book was never intended to be a comprehensive introduction to Chef, both O'Reilly and I took this on board, and began work on a "Definitive Guide" - a full-length, comprehensive book on Chef. And that's where the problems started.
Chef is a large project, with a very active community. It's also a young project, moving very quickly indeed. Any attempt to capture the 'recommended approach' at a point in time was quickly rendered obsolete. New features were being added at breakneck speed. New community tools were being developed, and 'best practice' was in a constant state of flux. It was clear that writing a 'definitive' guide was going to be a significant undertaking, and quite possibly a flawed one.
At the same time, interest in test-driven infrastructure was exploding. New testing approaches and tools were blossoming, dozens of talks and discussions were being had, and my little introduction to the idea was getting slammed by its readership for covering only one approach, for being too short, and for not being a definitive guide to Chef. Did I mention that writing books is hard?
I had to make a decision. With limited time available, with a busy speaking, training and consulting schedule, and a large family, where should I focus my attention? After discussions with O'Reilly, and friends and colleagues, I decided that I should work on updating the initial Test-driven Infrastructure book. Now, in microcosm, we had the very same problem of a rapidly growing toolset and community to deal with. Tools came and went, underwent complete rewrites, and best practices continued to evolve. I also felt it was necessary to try to give a more thorough Chef overview, in response to feedback on the first volume. I worked incredibly hard on the 2nd edition. Frankly, too hard. I made myself ill, got entirely burned out, and let down family, friends, colleagues and readers. But, by the time of Velocity, this summer, we were pretty much finished. I met with my editor at the conference, and we surveyed the landscape.
The much-hated wiki had been replaced by a greatly improved documentation website. Ospcode had hired a technical writer to work on documentation, and community engagement in improving and maintaining that resource was growing. We remained convinced that trying to write a "definitive guide" at this stage was not a wise choice.
Additionally, Seth Vargo had begun an excellent project: learnchef. Aimed at being the ultimate hands-on quickstart guide, this was immediately well-received, and together with my second edition, filled the requirement for an introduction to Chef. The intermediate, reference-level specification of the core Chef functionality was adequately covered by docs.opscode.com. What we felt was missing was deep-dive, subject-specific discussions. How do I build infrastructure on Windows? How can I build a continuous delivery pipeline using Chef? Advanced programming in the Chef environment. That sort of thing.
We agreed to cancel the definitive guide project, with a view to working on these subject-specific guides. I tweeted about this, more than once, and shared our intention with friends in the community. What we didn't do, either O'Reilly, or me, was make a formal, public announcement. That was a mistake. I can't apologise on behalf of O'Reilly, but I can apologise personally. That was unprofessional of me: I'm sorry.
So, it's now summer, and I'm utterly exhausted. But in the spirit of the invincible superhero, I continued to take on work, travel, speak, and generally over-commit. My physical and mental health deteriorated further, until late August when I had to accept I was at the point of complete breakdown. I took about 6 weeks off, recovered my perspective, got some good rest, and left the editorial process in the safe hands of O'Reilly, and Helena.
Fast-forward to now. The 2nd edition of Test-Driven Infrastructure is out, and early reviews are positive. I'm rested, healthy, and hopefully wiser. I've learned a lot about Chef, and about writing, and am ready to start on my next project... this time with co-authors from day one. I have ideas on what we should cover first, but I'm open to suggestions and requests.
In the meantime, we have good resources available. Use learnchef, join the IRC channels, participate in the mailing list, read my book. Matthias Marschall has just finished his book on Chef, which is also excellent. People who lament the quality of the official documentation - please: give specific examples of where you feel information is missing, the writing is poor, the material is misleading. Remember: this is a community project - if you think you can improve the documentation, submit a pull request, and make it better for everyone. Opscode is committed to great documentation, and the decision not to try to write a definitive guide forces us as a community to build this reference ourselves, openly.
To conclude - I acknowledge that I've let down the people who were so eagerly anticipating "The Definitive Guide". I also accept that we handled the communication of our decision badly. But I think it's the right decision. And I think we're in a strong position to move forward and build on the resources we already have as a community. Will you help?
No comments:
Post a Comment