User login

Talmud: Git version-controlled, free, open, collaboratively-written books the way G-d intended

Having experienced writing an epic tech book - 36 authors and 36 chapters and no, it did not break down nice and neat like that - we are convinced there is a better way than the traditional publishing model. Drawing on the tradition of open source free software about which we wrote, we propose donation-funded, completely free and open texts of superior quality and timeliness, marked by clean mark-up and powered by technologies of collaboration.

(For a good overview of the entire shift in author-reader-publisher relations, read Crag Mod's "Post-Artifact Books and Publishing".)

LaTeX is how a technical text should be typeset. It makes changes trivial, up to the moment ink hits paper, says Hedgemage, who offers to start the LaTeX conversion and teach it to people.

Git helps merging of people's work and especially enables parallel work on different parts of one cohesive whole.

We want to see if we can't raise more funds than we'd get in book royalties anyway to do this process right.

Project name

Name for the overarching project of collaborative, version-controlled writing: Talmud? "The Talmud is a massive work of multiple teachers and explainers working across distance and time to preserve and spread a vast array of knowledge."

Tried to think of the greatest collaboratively written book and all i could come up with is Talmud. The Torah or the New Testament or the Quran (i think?) also are books with many authors (at least the evidence is very strong for the New Testament), but there's the claim that they were written by God more or less directly that makes that less of a choice term- though "The Whatever Bible" is already a series of tech books.

When originally describing this idea as phase two of the Definitive Guide to Drupal 7 in IRC i used the phrase "git version-controlled, open, free books the way G-d intended".

Technical details

Do we really want Git version control? Or do we just want LaTeX on a wiki? We want Git version control. Books should be forkable, worked on individually or in a tight collaboration, and merged back to the main flow.

As diffs are line-based, it would be great to have a way where sentences were considered lines, rather than entire paragraphs, or that everything automatically wrapped and rewrapped at a certain width.

"Machine names" for chapters, which can be replaced with numbers (or not?) when the number and order of chapters is finalized.

The negative example

What we are reacting to in the DGD7 writing cycle.

Problem's due to the benjamin melançon style of doing things:

  • too much going on in parallel for ben to coordinate
  • many responsibilities left undefined

Problems due to the publisher's non-agile approach or otherwise squarely on the publisher's head:

  • changes to chapters turned in at the publisher's request and with plenty of time to go in, and accepted by the publisher with the statement that they would go in, are not in the page proofs. Our contact wrote in response: "I don't have a corrected proof. I have your changes you sent me, and they will be incorporated into the book. If you have anything else you want to add, then you can put it into the page proof on the dropbox, and I will incorporate those additional changes to the ones you already sent."
  • "For some strange reason, the compositor named a new of the files different from the rest. But that is the correct one."
    • They split my intromodule chapter into three and i'm ticked about it, but it was done too late to even fight. So i have my own complaints about the process and recommendations and please lay your complaints about my part or any part on me!

Overall: The author write, editor review, author revise, editor review, author proof pipeline proved inflexible and prone to logjams.


A one year write cycle.

Giving a month for every planned ten pages seems reasonable, from experience working with working authors.

So three months to produce a chapter.

Anyone who doesn't deliver after three months gets reassigned to an advisory role, and a new primary author found. (I (ben) would probably have lost all the chapters i ended up doing under this system, and that is fine.)

Editorial decisions

Domain experts would be given special authority over content whether they are authors or not. The point isn't democratic, but open.

As Sarahe says, not doing it "right" but doing it much, much better.

Searched words: 
Collaborative writing project biggest collective book best collaboratively written work


Many options, none perfect yet.

So, there are a bunch of people out there banging away at this very problem. Here are some of the solutions I've seen:

  • DocBook <--- I use this option, a lot of people get turned off by XML, but the DocBook XSLT along with FOP can produce print-ready PDF. Pros: It works, Cons: It isn't exactly what I would call "easy" for contributors. Not the easiest thing to diff.

  • LaTeX <--- Look at the Onyx Neon books by chromatic and Allison Randal, they use perldoc + LaTeX. Pros: It works, easy to diff. Cons: I don't know LaTeX output always tends to look like LaTeX output.

  • Markdown <--- There are a bunch of people using Markdown as a format for books. Pros: Easy, accessible for lots of contributors, Cons: Very rich, semantic markup starts to look very ugly.

  • Wikis <---- The Floss manuals people are all about Wikis. Pros: Easy for lots of contributors, Cons: You want to spend a year of your life in a Wiki?

Anyway, there are so many options out there, but still none of them is ideal. The most challenging problem is trying to get this output into drupal in a way that won't drive you crazy. the best solution I have found so far is Import HTML, but it gets no respect.

One issue with your post, you talk about finalizing chapter numbers. It might take a few years to get to this point for your drupal 7 book, but you'll probably want to revise this book going forward. I'm of the opinion that books are never "finalized". Using chapter numbers anywhere is a mistake, especially in links, and whatever format you use should be smart enough to handle crossreferences.

A flexible plugin that

A flexible plugin that generates a Table of Contents based on the HTML markup of the web page

And from the business / sustainability side

I'm thinking a mix of:

  • free e-books, by the sheer kindness and good-will of the author
  • fundraiser e-books like this one
  • e-books that pay for authors time
  • fundraising that goes to the author, and the e-book is free

Another excellent markup format suitable for git version control

If choosing simply on the best system (and not on what people want to use, which probably should also be taken into consideration) i would use

But i think if people are smart, they'll want to use ASCIIDoc

The full toolchain is free and open source— i found it independently of a near simultaneous recommendation by a friend who is doing major documentation with it when i became frustrated with LeanPub, Atlas at O'Reilly, and as far as i can tell, GitBook, keeping parts of the process proprietary and behind a paywall.

See also:

Post new comment

The content of this field is kept private and will not be shown publicly.
  • You may post code using <code>...</code> (generic) or <?php ... ?> (highlighted PHP) tags.
  • You can use Markdown syntax to format and style the text. Also see Markdown Extra for tables, footnotes, and more.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <img> <blockquote> <small> <h2> <h3> <h4> <h5> <h6> <sub> <sup> <p> <br> <strike> <table> <tr> <td> <thead> <th> <tbody> <tt> <output>
  • Lines and paragraphs break automatically.

More information about formatting options

By submitting this form, you accept the Mollom privacy policy.