Living the Future of Technical Writing
By: Scott Chacon
Tags: technical, book 

The amazing adventures and final toolchain of Pro Git, 2nd Edition

Almost exactly six years ago I was approached by Apress to help out on a book that was being written but was falling behind schedule called Pro Git. Eventually the original author decided not to keep writing and I rewrote the book from scratch, finally being published around August of 2009. For the first three chapters or so, I wrote the book in Word, sending documents to my editor and getting redline versions back some time later.

After about three chapters of this I was about to give up when I suggested that we switch to doing the book in Markdown for the writing and technical editing phase and then move back to Word only for copy editing which was agreed to. Once the book was completed, I again moved all the content back to Markdown so I could publish it online at a website I created. Luckily for me, the original author had gotten Apress to agree to Creative Commons license the work as well.

Over a year later, Apress also released a Kindle version of the book, though people had produced Kindle compatible versions from the open source content almost as soon as the book was released.

Pro Git, Second Edition

Since the book has done reasonably well, after about four years of being in print, Apress approached me to do another edition of the book. In the course of that time, my company GitHub had grown from being 4 guys working on a site for a few thousand users to a giant online presence hosting millions of repositories and employing over 200 people. Not only had the GitHub community changed that much, but the tool itself had also had some significant changes. I agreed that it was probably time to revamp the content.

While you can now read the second edition (as well as the first edition) online or download it in PDF, ePub or Mobi (Kindle) formats to read on your favorite device, I thought an interesting story to share would be the differences in how this version was produced from the first version about five years ago.

The Writing of Pro Git v2

I had actually started revamping Pro Git a few times in the last few years. Mostly I was interested in the toolchain aspects of it. At some point I started a project called Git Scribe which was meant to demonstrate the type of toolchain I wished I could have used to write Pro Git. The scribe tool provided a semi-easy way to install a toolchain that would take a specifically formatted Asciidoc book and produce nice looking HTML, PDF, ePub and Mobi ebooks from it. Though the project has since died and we ended up using O’Reilly’s Atlas platform instead, the Scribe project got me into Asciidoc in the first place.

Asciidoc

So I switched large portions of Pro Git to Asciidoc. The issue with Markdown was that it was too simple. It didn’t specify things like table formatting, cross references, indexing, callouts, source code examples, etc. All of which Asciidoc does in a format that is just as easy to write.

So I moved everything from Markdown into Asciidoc and noticed that some publishers were doing so as well. O’Reilly started allowing books to be written in Asciidoc since it generates Docbook easily and I believe Pragmatic Programmers had been using a simple markup language for a while before that.

Most importantly for all of this was the rise of Asciidoctor. When I went to redo my Git website (git-scm.com) I wanted to take the Asciidoc man-page sources for Git and make nice online versions of them and I wanted to do it with Ruby. My friend and GitHub coworker Nick Hengeveld wrote a nice parser and formatter for Asciidoc to help do this. Eventually some other GitHubbers (Ryan Waldron and Jeremy McAnally) joined in and turned Asciidoc.rb into Asciidoctor, which was eventually taken over by the amazing Dan Allen, who has taken the project to a whole new level.

Now that Asciidoctor is around, I can do truly amazing things with my Asciidoc source book that were not nearly as simple before.

GitHub

One of the biggest changes to the writing workflow was that GitHub is a lot better now than it was before. Now we had Pull Requests for review and commenting, Issue milestones for chapter planning, prose diffs for easier review and spot-checking, and the Atom text editor for writing and Asciidoc preview.

The workflow we got to use is one that everyone who has ever written a technical book, especially with a co-author, will probably be insanely jealous of.

We wrote out everything we wanted to do, added all the major points as issues attached to milestones for each chapter and then each decided what we were going to do and started writing. We could make a branch for the unit of work we were doing (normally a chapter) and start writing and pushing to the GitHub branch. We talked in Slack and got instant updates whenever one of us pushed some change. We opened a Pull Request almost immediately, usually with a checklist of things we wanted to complete before merging so you could tell what the status of each branch was (example).

When a branch ran long, we could merge the master branch into it to keep it up to date and make sure that conflicts were never a huge problem even through massive structural changes like splitting up chapters into multiple files.

Review was done through the Pull Requests — we could leave comments on any line of introduced text and have a conversation either there or in chat about it.

I was able to install the Asciidoc Atom preview plugin and get live rendered views of the text I was writing as I was writing it, including sidebar hints about what I had added, modified or deleted, what branch I was on, merge conflict helping tools, zen mode, etc. It was an amazing writing environment.