Open is better than closed because when you work in the open the whole world can help you (or at least the portion of the world that cares about what you are doing). For books in particular, readers can be tremendously helpful by submitting typo fixes to the book. But how can users submit typos? Surely there is something better than email…

Today I saw a very interesting workflow for reader contributions on the Advanced R programming book website by Hadley Wickham. The book  is being developed on github using the Jekyll static site generator. Each page has an “Edit this” link on the right side:

 

The url for that button is:

https://github.com/hadley/adv-r/edit/master/index.rmd

Clicking on that takes you to github and a special prompt to create a fork:

Next you can make the change:

 

And finally the UI offers you to do a pull request:

This is still a complicated process for the reader (3-steps, one feature branch, one pull request), but from the author side this is awesome! You just write and then manage incoming pull requests that improve your content.

Anyone writing their blog posts in the open on github should consider adding the /edit/ links.

 

Weekend project: find a way to automate this workflow process so readers don’t need to have github accounts. Maybe I could create a “shared” github account “ivans-readers,” allow for login-less-editing to happen on my own server and then see the pull requests coming from ivans-readers on the main repo.

2 thoughts on “Open book writing and typo workflow

  1. Git for authors – Minireference blog
  2. Annual general update – Minireference blog

Leave a Reply

Your email address will not be published.