Skip to content

Instantly share code, notes, and snippets.

@skopp

skopp/authoring_books_with_github.md

Created May 1, 2013 00:59
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save skopp/5493068 to your computer and use it in GitHub Desktop.
Save skopp/5493068 to your computer and use it in GitHub Desktop.
Download ZIP
#book #authoring #teach #github
Raw
authoring_books_with_github.md
layout title description path
barewithrelated
Book Authoring Using Git and GitHub
Formats, tips and techniques for using Git and GitHub as the version control and collaborative platform for writing short and long form books.
usecases/_posts/2001-01-01-book-authoring-using-git-and-github.md

Git and GitHub 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.

Inspirations

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

Format, Authoring Tools

  • Scribe
  • 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
  • XML
    • For pure XML (DocBook) authoring, I liked:
    • Some of these have DocBook stylesheets built in or a live editor
  • 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

Outlining strategy/hacks

  • 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?

  1. Level one bullets only. Revise. Review.
  2. Write 5% of the book based on passion.
  3. Level two bullets. See impact on level 1. Revise. Review.
  4. Consider the outline locked unless there is something massively broken.
  5. Write a crappy first draft with high velocity.
  6. Stick to the outline. If you need to change it, change it, but don't let the prose drive the plan.

Writing Hacks

  1. 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.
  2. 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.

Task tracking

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:

Contract management

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

Integrated Reporting

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment