How to win friends and write an open-source book

class: inverse, left, middle, nonum, clear
background-image: url("figs/scover.png")
background-size: cover

# HOW TO WIN FRIENDS & WRITE AN OPEN-SOURCE BOOK

### https://geocompr.github.io
.LARGE[Jakub Nowosad, Robin Lovelace, Jannes Muenchow | useR! | 2019-07-12]

---
# The Geocomputation with R book

.pull-left[
<img src="figs/cover.png" width="75%" style="display: block; margin: auto;" />
]

.pull-right[
- **Geocomputation with R** - a book for people who want to analyze, visualize and model geographic data with open source software
- Two years in the making
- Three main parts: Foundations, Extensions, and Applications
- The online open source version of the book is hosted at https://geocompr.robinlovelace.net
- This book has now been published by CRC Press in the R Series - you can buy the book from [CRC Press](https://www.crcpress.com/Geocomputation-with-R/Lovelace-Nowosad-Munchow/p/book/9781138304512), [Wordery](https://wordery.com/geocomputation-with-r-robin-lovelace-9781138304512), or [Amazon](https://www.amazon.com/Geocomputation-Chapman-Hall-Robin-Lovelace/dp/1138304514/)
]

---
# The book beginnings

.pull-left[

- Robin and I first met in June 2016
- We both have taught several courses related to spatial R
- We have also used R in our research projects
- We shared an idea of writing an R-spatial book
- **The main book audience were imagine as ourselves just a few years before**
]

.pull-right[
<img src="figs/rl-and-jn.jpg" style="display: block; margin: auto;" />

]

---
# The publisher

.lc2[
A few months later, we sent our proposal to publishing companies.

Our book uses **a hybrid system**, in which books are published online *and* in print:

- People can choose how to read the book and make an informed decision before buying it
- The book retains the process of reviews and professional copy-editing provided by publishers
- The wider community can contribute, leading to many improvements in the code and text

Of course, you can always [self-publish a book](https://blog.datascienceheroes.com/how-to-self-publish-a-book/)...

]

.rc2[
<img src="figs/john-kimmel.jpg" width="70%" style="display: block; margin: auto;" />

[Publishers allowing for a hybrid model books:](https://twitter.com/robinlovelace/status/1144150567759073286) CRC Press, O'Reilly, OTexts, Princeton, Cambridge University Press

Self-publishing venues: Lulu.com, leanpub.com, Amazon.com
]

---
# The book infrastructure

.pull-left[
**Several developments have enabled this:**

- [**Bookdown**](https://bookdown.org/yihui/bookdown/) - R package built on top of R Markdown; complete solution for creations books in multiple formats (PDF/HTML/Word/…); allows for numbering and cross-referencing figures/tables/sections/equations, etc.
- [**GitHub**](https://github.com/) - stores the book code; allows for collaboration 
- [**Travis CI**](https://travis-ci.org/) - automaticaly builds the book after code changes
- [**Netlify**](https://www.netlify.com/) - hosts the book website
- [**Zotero**](https://www.zotero.org/) - stores the references
- **Existing R packages** - e.g. [citr](https://github.com/crsh/citr) - eases inserting citations; [kableExtra](https://github.com/haozhu233/kableExtra) - creates tables
- **New R packages** - [geocompkg](https://github.com/geocompr/geocompkg) - allows for installing of all packages used in the book; [spData](https://github.com/Nowosad/spData) - contains data used in the book
]

.pull-right[
<img src="figs/logos.png" width="100%" style="display: block; margin: auto;" />
]

---
# An open source book

.pull-left[
<img src="figs/geocompr-github.png" width="1100" style="display: block; margin: auto;" />
]

.pull-right[
**We decided early on to develop this book in the open to remove financial barriers to learning open source software.**

It also enables community contributions, which we (still) encourage on any part of the book, for example:

- Improvements to the text, e.g. clarifying unclear sentences, fixing typos
- Changes to the code, e.g. to do things in a more efficient way
- Suggestions on content in the issue tracker
]

---
# Collaboration: a few tips

- Start with an outline, but don't be afraid to change it later
- Schedule regular time to write - make it a habit
- Have [a book style](https://github.com/Robinlovelace/geocompr/blob/master/our-style.md), e.g. **package**, `function()`, `=`, `en-us` spelling
- Stay in touch with your co-authors - regular contact: [Gitter](https://gitter.im), [Skype](https://www.skype.com/en/)
- Keep a feedback loop going
- Be kind and positive
- Oh... and one line per sentence!

---
# The third author

.pull-left[
<img src="figs/jannes.jpg" style="display: block; margin: auto;" />

]

.pull-right[
- A few months into making the book, Robin and I were contacted by a postdoc at Friedrich-Schiller-University Jena and an author of the [RQGIS](https://github.com/jannes-m/RQGIS) package
- **Jannes Muenchow** firstly gave us a concise idea about a chapter showing how to bridge R with traditional geographic information system software
- Next he wrote a high-quality piece of text and code
- **Finally, he became the third author of the book!**

]

---
background-image: url("figs/spatial-authors.png")
background-size: cover
# An open source cycle I

.pull-left[
**Existing R packages**, including:

- [sf](https://github.com/r-spatial/sf)
- [raster](https://github.com/rspatial/raster)
- [tmap](https://github.com/mtennekes/tmap)
- [mapview](https://github.com/r-spatial/mapview)

**Existing software**, including:

- [GDAL](https://gdal.org/)
- [PROJ](https://proj.org/)
]

---
background-image: url("figs/our-impact.png")
background-size: cover
# An open source cycle II

.pull-left[
**[Our impact](https://github.com/Robinlovelace/geocompr/blob/master/our-impact.csv)**:

- Reporting bugs
- Clarifying documentations
- Proposing enhancements
- Pull requests

]

.pull-right[

]

---
# An open source cycle III

.pull-left[

*David Cooley*
<img src="figs/02-impact1.png" width="1087" style="display: block; margin: auto;" />

*Roger Bivand*
<img src="figs/02-impact2.png" width="897" style="display: block; margin: auto;" />

*Tim Appelhans*
<img src="figs/02-impact4.png" width="875" style="display: block; margin: auto;" />

]

.pull-right[
**Existing packages authors' feedback**:

- Comments
- Suggestions
- Reviews
- Pull requests

*Chris Reudenbach*
<img src="figs/02-impact3.png" width="975" style="display: block; margin: auto;" />

]

---
# An open source cycle IV

.pull-left[

<img src="figs/frontcover.png" width="484" style="display: block; margin: auto;" />
]

.pull-right[
**Readers input**:

- Comments/suggestions/questions/requests (more than 200 GitHub issues)
- Pull requests  (more than 200 GitHub pull requests)
- Even the book cover image!

<blockquote class="twitter-tweet" data-lang="en">We are pleased to announce that the winner of our geocompr book cover competition is Marco Sciaini (<a href="https://twitter.com/msciain?ref_src=twsrc%5Etfw">@msciain</a>). Now we are working with him on a final version of the book cover. Thanks for all your submissions!&mdash; Jakub Nowosad (@jakub_nowosad) <a href="https://twitter.com/jakub_nowosad/status/1034850749669404672?ref_src=twsrc%5Etfw">August 29, 2018</a></blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
]

---
# Additional materials

## https://geocompr.github.io/

**It contains:**

.pull-left[
- Presentations
- Workshops materials
- Guestbook
]

.pull-right[
- Book exercises' solutions
- Extended examples
- Additional articles
]

---
# Community

.pull-left[
<img src="figs/geocompr-org.png" width="533" style="display: block; margin: auto;" />

]

.pull-right[

**The Geocomputation with R book is alive**:

- [Twitter](https://twitter.com/hashtag/geocompr) - #geocompr, #rspatial
- [GitHub](https://github.com/Robinlovelace/geocompr) - new suggestions/questions/requests and pull requests are still being added

]

---
# Closing notes

.pull-left[

**Issues:**

- Having consistent html and pdf versions, especially when using a publisher LaTeX style

- Relating book code chunks outputs to their code
- Connecting exercises to the solutions
- Formal reviewing process do not use GitHub issues/pull requests
- Formal copy editing do not use bookdown

]

.pull-right[
**How to start:**

- Visiting https://bookdown.org/
- Xie, Y. (2016). Bookdown: Authoring Books and Technical Documents with R Markdown. Chapman and Hall/CRC. https://bookdown.org/yihui/bookdown/
- Trying the bookdown demo at https://github.com/rstudio/bookdown-demo
- Reading source codes of existing books, e.g. https://github.com/Robinlovelace/geocompr, https://github.com/hadley/r4ds
]

---
class: left, top, clear

### **Slides:** http://bit.ly/user2019-geocompr

.pull-left[
## Summary:

- Writing a book is hard, but very satisfying
- Collaboration is crucial

- Most parts of the book creation infrastructure is already here
- Thank you all!
]

.pull-right[
## Contact:

Twitter: #geocompr

Twitter: jakub_nowosad

Twitter: robinlovelace

## Resources:

https://geocompr.github.io/

https://nowosad.github.io

https://www.robinlovelace.net/
]