It Takes a Village to Write a Book

Note: As I was about to publish this post that I started on November 27, we made the (somewhat crazy) decision to push back the publishing of Laravel: Up and Running's second edition by about a month so we can cover yet another version of Laravel in it. So, these stats are all for the original 5.7-covering version of the second edition; imagine all of them being even a bit higher once we update it to cover 5.8.

I just finished writing and editing the second edition of my book, Laravel: Up and Running! WOO WOO! Here are a few quick statistics for the work that went into the second edition:

• 32 files changed
• 9521 insertions
• 6124 deletions
• 548 commits
• 31 weeks
• 1 author (me)
• 1 research assistant (Wilbur Powery)
• 3 tech reviewers (Samantha Geitz, Mohamed Said, Tate Peñaranda)
• 1 editor (Alicia Young)
• 1 production editor (Christopher Faucher)
• 1 copyeditor (Rachel Head)
• 1 indexer (?)
• 7 email chains with the O'Reilly tooling support
• 1 new chapter (The Laravel Ecosystem)
• 1 entirely re-written chapter (Testing)
• ??? new Laravel tools added
• 516 total pages of content

There are a lot more fun stats I could probably come up with but, to be honest, I'm tired of working on this book and I want to see it get published now!

While it's in the hands of the O'Reilly production and QA team, though, I wanted to share a little bit of what it's like to write a book like this. I've often seen folks self-publish a book without any editors or proofreaders or anything, and especially with the second edition of my book, I took basically the opposite approach. So, I wanted to share a bit of who helped me—both the broader roles, but also the specific people.

There was a similar group of people who helped me in the first edition, but I'm going to be writing up my second edition team here because I made a big shift in how I wrote the book that I want to share.

The O'Reilly Structure

Most of how my editing process worked was the traditional O'Reilly structure. I wrote the book in git, in AsciiDoc, using the MarkdownEditing plugin. Here's what it looks like:

Once I finished writing in any session, I would push it up to O'Reilly's Atlas platform, where my O'Reilly editor could review it and we could both generate previews:

Editor

Once I had finished a chapter, or a series of chapters, I'd get high-level editorial insight from my O'Reilly Editor, Alicia Young. These edits would be things about writing style and communication; here's one of her notes from my testing chapter:

The idea of fidelity of tests isn't really discussed elsewhere. Is that something your readers will be familiar with? I admit I had a hard time understanding the distinction based on the examples you give after this statement, so you may want to add another line of explanation further clarifying this term in this context.

She gave me 73 comments on chapters 12-18, for example, most of which were minor wording changes to make a sentence clearer.

Tech reviewers

I had a group of tech reviewers that I found who were willing to read through the whole book for a small stipend and give any notes they found. These were usually technical issues—ranging from "You keep referencing Eloquent but we haven't had the Eloquent chapter yet" to "What about referencing the @csrf helper here?" to "I don't think this code would actually work."

Production

I can't say I remember exactly everyone who's involved in production, but here's what I know so far.

I know I have a production editor who is, as the name suggests, the editor of the production process. They'll be responsible for getting all the right people lined up to take their crack at the book, from copyeditors (who mainly handle writing-related issues) to indexers (or whatever you call the people who mark the book up for the index) to layout people who handle weird page breaks and stuff like that.

There's a lot that goes on here, and most of it is entirely outside of my world—I just watch the git commits roll in, and at one point I get a PDF of notes from the copyeditor to review.

My own setup

Outside of the setup that O'Reilly provides, I've also brought on a little bit of help. For the first edition, I brought in a different group of wonderful tech reviewers into O'Reilly's system. I also got help in the form of a few of the early readers giving me some proofreader-style feedback after we released the book, which I was able to incorporate into later releases (thanks to all of you!)

For the second edition, I knew the book was ready for a big refresh (it covered up to Laravel 5.3 and we were now on 5.5, heading toward 5.6). But I just didn't have time. My wife's acting career is taking off, my kids are getting older, Tighten is busy and I just don't have dozens of hours a week to spend updating the book.

A research assistant

But, I had an idea: I would hire someone to handle two primary jobs: combing through the release logs and docs changes of the last few versions of Laravel to make sure we updated everything, and then running all of the code samples in the book in the latest version of Laravel to make sure it worked.

I hired my friend Wilbur Powery to take on this task, and he became my research assistant, sending in pull requests with small modifications to the code samples or some of the documentation, or any time it was more than just a syntax change, leaving me a note inline that I should write or delete or modify a bigger section.

With this help, I was able to essentially ignore the book for weeks at a time while Wilbur would research the next chapter and deliver his notes. Then, once each chapter was done, I would approve all of his minor edits, and then sit down to write or re-write any bigger sections that had changed significantly.

The printout

Once that was all done, I printed the entire book and had it bound. I read the entire book cover to cover over the span of a few weeks, poring over every sentence and example with a pen or marker and a huge stack of mini postit page marking tabs.

Once that was done, I entered those changes in manually.

Next steps

I mentioned this on Twitter, but as I was about to publish this article, we discovered the book wouldn't go to print until early February 2019, which is right around when Laravel 5.8 was going to come out. So, I worked with my editors to add a bit of time into the production timeline so we can update it for 5.8 and then push it out in early March.

Here's a really rough timeline of events—(without dates, but you can at least see what the order is like:

• Suggest book to publisher
• Negotiate contract and rough timelines
• Write book
• Get feedback from editor and tech reviewers—preferably in small chunks as writing progresses but sometimes in larger chunks as half or all of the book is done
• Personal review
• Send the final-ish copy to Production
• Copy editing (and me reviewing the edits)
• Indexing (and me reviewing the index)
• Final review
• Files to printer and eBook generation
• Book delivered to sellers

I think that's all for now. Off to get Wilbur and me started with making a list of edits for 5.8!