Wednesday 12 March 2014

Managing LeanPub book's Markdown content using Git and GitHub (synced to back to LeanPub via DropBox)

The original releases of my Practical AngularJS and Practical Git books were made using LeanPub's DropBox model, which was OK, but lacked two massive features: version control and interface for community interactions.

Inspired by Dennis Groves' idea and workflow described in OWASP Press and using LeanPub with GitHub and DropBox, I was able to use Git and GitHub to track changes on these books.

Which means that from now, not only can I use the GitHub repositories to track/document changes I make, but you can also submit your ideas/problems directly as GitHub issues and fixes as Pull Requests :)

Here is the GitHub repo for the AngularJS book: https://github.com/DinisCruz/Book_Practical_AngularJS

Here is the GitHub repo for the Git/Hub book: https://github.com/DinisCruz/Book_Practical_Git

For an example of how to use GitHub to submit and fix an content problem see this issue https://github.com/DinisCruz/Book_Practical_Git/issues/1 which was fixed by this commit https://github.com/DinisCruz/Book_Practical_Git/commit/7c53c396f4209bb2521dccadbfcfbe8c90318ba7

This technique was also inspired by the Lean Publishing Manifesto  and specially by this paragraph in the LeanPub Author FAQ
"More broadly, Leanpub is based on the idea that it's absurd that in 2012 there was no good way to write a book. Using a bunch of Markdown files is the best thing we have come up with, but fundamentally most of the ways that people write and publish books today are just barbaric. Proprietary document formats, unreliable programs, no ability to version control your files and see meaningful differences, no way to interact with your readers as you write, etc. We might as well be using typewriters or quill pens. We're doing our part to help fix this global catastrophe; will you do yours? :)"
So by adding Git/HubHub to the LeanPub book creation workflow, we start to have an end-to-end digital book creation experience, with version control and social interaction.

There is still a lot to go until we have a really nice and smooth experience (maybe with commits made to GitHub triggering the creation of a preview), but as it stands there are already a number of really powerful technologies/techniques at play:
  • Markdown: for content creation
  • Git: for version control and distributed authoring
  • GitHub: for managing issues and community contributions (via Pull Requests)
  • DropBox: to sync data with LeanPub (from a local git repo)
  • LeanPub used to create eBook versions (pdf,mobi, epub),  sell book via dedicated web page and provide a management website for authors to manage the entire publishing+sale process.
The LeanPub cog is the one that glues all this together, specially when it creates such nice pages for authors: see https://leanpub.com/Practical_Git and https://leanpub.com/Practical_AngularJS

As requested by the LeanPub Author FAQ, I'm doing my bit in helping fixing this global catastrophe; are you doing yours? :)

UPDATE: see this interresting GitHub Issue thread about the current Blogger-to-Markdown-to-Git-to-Leanpub workflow: