Media folks and other non-technical writers don’t know enough about GitHub.

Let’s fix that.

A remarkable amount of my writing is now done collaboratively. As a result, I’ve been on an odyssey for better tools and have landed in an unexpected place: GitHub. (Yes, I use G Suite a ton, but it falls down when working on long, complex documents and on creating something that’s beautifully typeset.)

While GitHub is often thought of as a repository for open-source software projects, I’ve integrated it into three recent Working Paper projects that have almost nothing to do with code. I’m currently using GitHub to collaborate on large reports, to power, and most interestingly to create a new “book.”

When telling a client about this, I realized how few people (besides software developers) have any idea at all about what version control is, let alone what they might do with a system built on top of it, like GitHub.

Writing a book (and building an organization) in a source-control system? Yep.

The most interesting example first: we’re starting a non-profit organization to support the creation and updating of a “text book”. By way of background, my collaborator Paul Glader and I are collecting resources for teaching entrepreneurial journalism because the next generation of journalists need a new set of skills: how to operate an organization. Throughout their careers, we expect them to freelance, start new enterprises, and report on businesses.

However, the typical way of distributing an academic primer – a book – is plainly ridiculous in this arena. Things change too fast. Clearly, we’ll be delivering content over the Web. But a Wiki doesn’t quite work either; we want authoritative voices writing on teach topic. But by putting the text into a public GitHub repository, anyone in the world can propose edits, to be accepted by an established author. Further, thanks to a feature called GitHub Pages, the text can be written in Markdown and yet displayed as a beautiful Web site. Also, it’s entirely free.

Web site publishing

GitHub Pages (powered by a static-site generator called Jekyll) also means you can host other sites for free. Better still, there is simply no content management system. Write a text file either in your browser or on your device and push it up to GitHub, and your entire site is rebuilt. This is particularly valuable for working on an iPad – a simple text editing app can now be a Web editor. There’s a burgeoning collection of nice looking themes, too. And again, did I mention it’s free? Anyone who has visited recently (which is, admittedly, approximately five humans), might notice that I’ve converted it over to Jekyll and GitHub, too. There’s a future post (next month) in how you can use the markdown source you write for Jekyll to automatically generate a nice-looking newsletter, too.

Collaborative, long-form documents

Last, Overleaf syncs to GitHub, meaning that I can write and update LaTeX documents on my phone. Better still, any edits I make are merged back into the main document, meaning collaborators get the updates. And the results are well-structured, beautiful PDFs, like my recent Shorenstein Center report.

There’s clearly more here – but too much for a newsletter. If you’re interested, just reply and lets talk.


  • Two common sense media links this edition, one about retaining digital audience and another on how media build trust with said audience. Both seem painfully needed.
    • In some of my favorite research to come out of Medill in years, the Integrated Marketing Communications faculty churned through massive amounts of subscriber data to help prove out what we should have already known: that optimizing for stories that get read in their entirety, and for reading multiple stories per session, helps retain subscribers. It is better than optimizing for page views. Also note: this came from serious, quantitative researchers on the marketing side of the house. We need more of this, and them. There is no more pure journalism.
    • In another obvious finding, but one I’m glad to see, newspapers are building audience trust by explaining how they do their work. This is, again, common sense, and makes for great storytelling. Who doesn’t like a behind-the-scenes look? The more we can show how we craft stories, the better.


  • As I promised in the last edition, I’ve codified a bunch of what I’ve learned about open-source IoT hardware into a single page.
  • This post walks you through what you need to build your own $5 WiFi temperature and humidity sensor.
  • If you’re in the Boston area, I’m giving a seminar on March 7 at the Berkman Klein Center for Internet and Society on this very topic. If you’d like to come, register here. (I’ll email you to confirm there’s space.)


  • On pain of going down the credit-card-points-rabbit hole, I will simply point out that the American Express Platinum Business card now gives you a year subscription to WeWork. You can visit as many locations as often as you wish. The $600 annual fee is 1/3rd the price of what I paid for my old co-working space. Needless to say, I signed up instantly.

I’m Reading

I’m Listening To