Book Authoring Using GitHub and Git
Formats, tips and techniques for using GitHub and Git as the version control and collaborative platform for writing short and long form books.
GitHub and Git are not just for writing programming code. They can also be an effective tool for writing articles and books. Matthew McCullough has written a quick guide to writing books in lightweight formats. This article will be folded into this Teaching repository over the coming months.
What is this?
This is a repository of ideas, techniques, tools and tricks on how to write a technical book. It was started by Matthew McCullough, and added to by Phil Haack, Dan Allen, Neal Ford, and Nate Schutta, and all the committers you'll see in the repo history. I just didn't want to hoard any knowledge that would help inspire others to write a technical book.
The contents of this repo have been partly invented from colleague conversations at O'Reilly during the Gradle book with Tim Berglund and Pearson during the Presentation Patterns book, partly inspired by open source projects, and partly refactored from snippets from colleagues and friends. Many are attributed.
Digital Toolchain for Book Authors
Text markup and structure
- So many light markup formats to consider
- Get handy with PanDoc (but man, the haskell bootstrapping is a pain)
- List of formats:
- Wikipedia Markup Formats
- Prefer AsciiDoc due to its ability to output DocBook
- Markdown is nicely rendered by GitHub and other desktop tools, but really isn't a full book authoring format.
- We used OrgMode for outlines and planning
- We used Dropbox for syncing it all
- We used Markdown for any quick write-ups and to-be-integrated raw pieces stored in a separate directory
Format, Authoring Tools
- Your Own Toolchain
- Will try to OSS some of this stuff in the Spring and I'll be hacking on Scribe as I give more time to GitHub employment
- The drawback to AsciiDoc is the lack of not having the full DocBook tag vocabulary
- You can always convert towards the end of the book and use DocBook from there on out, but that seems like a nasty mode shift.
Inline Code Samples
- Q: Code insertion (such that it can be tested)
- AsciiDoc uses pygments to style the most common languages
- Nest the examples as a Git submodule within the Git scribe book or other book technology. You can OSS the examples early. We did with Gradle.
Example code in Asciidoc (standalone files)
[[EX-MAVEN-001]] .The smallest possible Maven pom.xml ==== [xml] source~~~~ include::example_code/maven-smallest-maven-pom/pom.xml source~~~~ ====
Audited version history
- Q: Naturally, we both prefer Git
- Git, without a doubt, but with more than just a master branch
- Squash branch commits for bigger "units of work", not noisy commits which some of my co-authors seem to like to create
- CIed book build
- Used just shell scripts and cron
- Or trigger on Mac folder changes with Hazel
Inline comments and threads/discussions
- Q: GitHub comments?
- Remarks DocBook tags in the DocBook files (Presentation Patterns)
- Q: How did you avoid 10 rewrites?
- A: Let it bake for 2 years in outlines and 1 year in a draft. INSANE. But nice.
So, how can this be done in a more reasonable way?
- Level one bullets only. Revise. Review.
- Write 5% of the book based on passion.
- Level two bullets. See impact on level 1. Revise. Review.
- Consider the outline locked unless there is something massively broken.
- Write a crappy first draft with high velocity.
- Stick to the outline. If you need to change it, change it, but don't let the prose drive the plan.
- Use Dragon Dictate and a Plantronics wireless boom mic. Thank me later. I cranked out 5200 words in a day with it. And you can listen to music while you dictate.
- Write every day. Even if just a little bit. I am the worst offender of this advice, but I am trying to stick to it.
- Q: We've been evaluating trello.com
Sample of OrgMode (Raw)
* Admin: Deadlines: ** Initial Marketing <2011-12-19 Mon> **** DONE Snappy back-cover text <2011-12-19 Mon> :nf:mm:ns: **** DONE final(-ish) TOC<2011-12-19 Mon> :nf:mm:ns: ** First Draft :nf:mm:ns: This is the draft that goes to Eileen & our technical review, not to be confused with Pearson's process ** Final Draft <2012-02-15 Wed> :nf:mm:ns:
Publishers are in the dark ages with this sending shredded trees all over the place asking you to physically sign 6 copies of a signature sheet. WTF!? Ideally this idea would integrate with electronic document handling like GH uses for its new employees.
via Phil Haack
Royalty and sales reporting typically sucks. Outdated sites that make Geocities look like the next GH. This site could provide a nice reporting dashboard for authors to look at.
Basically, this could be the one stop shop for publishers and authors to collaborate on a book.
via Phil Haack