The book writing experience

This article is part of an archive of articles that were formerly on the web site of Poplar ProductivityWare LLC, Jennifer's freelance software development business (which closed for business in April 2022).
Author: Jennifer Hodgdon
Date Written: 10 January, 2013
Type: Article
Subject: Drupal

I finally got a copy of my new book, Programmer's Guide to Drupal in the mail yesterday -- it's very satisfying to see it in print. Maybe you'd think someone who makes her living almost entirely by electronic means would stick to e-books, but ... call me old-fashioned, but I still do like reading paper. So, while e-books are poised to outstrip paper books (especially for technical books) any day now, I am glad that my book is available in paperback too, and it's tangible and very satisfying to hold.

I thought this might be a good time to reflect a little on my experiences with the publishing process, now that the book is out (I expect I'll be doing revisions as time goes on, including a major update when Drupal 8 comes out, but for the moment I'm done). Overall, I have to say that the experience of writing a book and publishing it with O'Reilly was positive:

  • I have always liked doing technical writing, so I enjoyed the writing process itself.
  • Of course, I am quite enamoured with both programming and Drupal, and I have a great interest in technical documentation, so I was quite passionate about the subject and about conveying the ideas I put into the book. That was what kept me going.
  • I had a great editor, Meghan Blanchette, who supplied me with very constructive suggestions and quick answers to all of my questions (this was the first time I had ventured into the publishing world, and it was all new to me).
  • O'Reilly has several options for authoring software, and the one I chose (AsciiDoc) allowed me to do the writing in a plain-text editor and submit changes using Git. This meant I could write the book using the same tools I use every day in my professional and volunteer Drupal work. AsciiDoc was easy to learn and intuitive, and for the most part enabled me to just concentrate on the content.

There were only a few not-so-positive aspects to the experience:

  • The O'Reilly AsciiDoc system had a few glitches and bugs here and there, which occasionally stood in the way of writing. The Tools team at O'Reilly fixed the bugs and answered my technical queries pretty quickly, though, so this wasn't a huge problem.
  • My account in the O'Reilly Author Portal was not set up correctly initially. There's a lot of good information in the Author Portal that I didn't have access to, which would have helped me feel a little less lost in the publishing process, and probably would have meant a lot fewer questions to Meghan along the lines of "what happens next?". Unfortunately, I didn't realize this until way at the end of the production process (how would I know what information was supposed to be there?). So... If you start working on a book with O'Reilly and you don't see a "Welcome Kit" in the author portal, ask about it!
  • The proofreading step in the final publication process was ... painful. I'll leave it at that.
  • I felt like communication kind of broke down during the final publication process, when Meghan handed the reigns over to the Publication department. I wasn't kept very well informed about the process (again, having access to the Welcome Kit would have helped if I had known!), and strangely enough, no one emailed me at the end to tell me we were done and my book was out (I found out by accident via Twitter, which I barely use). This left me feeling like the process was a bit out of my hands (which I guess it was, to some extent) -- quite different from the earlier steps when it was mostly up to me.

All in all, it was a positive and very satisfying experience! I'd even consider doing it again, and I'm certainly, on balance, looking forward to rather than dreading the major revisions that will be needed for the Drupal 8 edition, hopefully sometime later in the year. If you have any ideas for other Drupal books that need to be written, drop me a line!