Teddy Hyde is the mobile GitHub editor for Android. Especially suitable for authoring your Jekyll blog: upload images, write draft posts, and preview Markdown with a quick swipe. Download it on Google Play.
16 October 2018

Four thoughts for Internet creators, as we release our book to Creative Commons

Looking over the speaker list at GitHub Universe, there is much to be excited about: in particular, can’t wait to see the archive of Lin Clark’s presentation; her amazing recent post for Mozilla about WebAssembly and JavaScript shows an exciting new frontier for the web. Universe started today, and sadly this will be the first year I won’t be attending in person.

I started attending three years ago when my co-author Ben Straub and I were almost finished with the book Building Tools with GitHub, which O’Reilly published in 2016. I’m happy to announce that O’Reilly has agreed to open source the book under creative commons, which means you can read it online for free, download the entire repository, create a customized PDF, or however else you might want to remix it.

This feels like a moment of closure in a long (5+ years!) process of writing and editing a book. The emotionally challenging process of writing it is already available online in various forms (see “Sending two signed copies of my book to a guy I’ve never met in Michigan”), so no need to revisit the past. But taking the book in this direction is a good moment to have a discussion about the future of publishing things like books, specifically on the Internet. It’ll just take a minute or two, trust me!

Here are some big questions which we don’t have great answers for right now:

  1. Is the “book form” narrative still relevant (especially for technical content like the material covered in this book)?
  2. How do we compensate creators on the Internet, again, especially when their work is in book form?
  3. How do we make it easier for people who read things on the Internet to adapt the content they are reading to their unique experiences?
  4. How do we make it easier for people who are reading to offer their comments and suggestions?

(If you want to skip the write-up and just see some of these proposed solutions in action, you can head over to the 2.0 version of Building Tools with GitHub (https://btwg2.teddyhyde.io) which shows off “cryptocurrency micro-contributions”, “perfect for who you are right now” customization ☃, and “mobile friendly collaborative editing” ✏️)

Is the book form narrative still relevant?

This post is worth reading only if you believe that “book form” technical content is important. There are signals in both directions. On the one hand, much of the content in the book was outdated the second it hit the repository, and often could be considered “outright and offensively incorrect!” the second the ink hit the page for the printed copy. As soon as the book went to print, GitHub announced the GraphQL enabled version of their API, which made much of the book content centered around their original RESTful API seem antiquated (though still entirely relevant if your language binding talks REST, which is still the majority of them!).

And, there still is much of the API that is not supported by GraphQL (mutations of commits, objects and trees, for example) which means the RESTful discussion of the Git Data API is still really important and really deserved of discussion. One of the motivations for writing the book was that I didn’t find any discussion of these more complicated topics and I didn’t find many discussions where these technical concepts were applied with real examples instead of highly abstracted examples like you find on the GitHub API documentation.

Being out of date is one thing. But, technology books still present ideas about technologies that are missing from blog posts and automatically generated documentation. One of the moments in writing the book that sits most present in my mind was the time right on the eve of publishing the book when the code for the Android chapter broke suddenly. GitHub updated their API ever so slightly (a security fix to make sure commits made via the API do have an author name or email, something up to that point they did require). That change broke the code in the Android chapter. I’m proud to say that the tests I wrote for that chapter (early on we made the decision that every chapter should have some form of tests) showed me quickly in my code where things broke. The java library (egit) which wraps the GitHub API didn’t give me a way, however, to easily surface the error from the API, so I used the MITM proxy tool to inspect the raw API request and response made by Android itself, and then retrieved the error from the API. I thought this was an interesting story that should be included in the book, but my editor thought otherwise, and I removed it.

Isn’t this kind of multifaceted discussion sadly missing from most blog posts: where do you see a discussion of building something that includes the mistakes made along the way? For the new generation of software developers, it is important to show the “experts” making mistakes, and figuring out how to fix them. I’m not saying that blogs don’t show that; they at times do, but since you have the full repository to this book, you can now see all those mistakes we made in writing it if you want to, which is a freedom of insight you don’t get from a static blog page.

How do we compensate people who publish things on the Internet?

We are in the golden age of compensation for Internet creators (right?). Sites like Patreon and Drip from Kickstarter present new tools for deeply connecting with an audience, making it seem like you could really make a living with 1000 True Fans as described by Kevin Kelly. Brave is another option that uses a variant of Ethereum Tokens, but strongly held opinions about Brave often seem to overwhelm the discussion of what they are trying to do (Brendan Eich is still an extremely polarizing figure in the tech world, and even getting funding via an ICO sale hasn’t prevented conversations about their profit motivations). Most importantly, all these solutions are very US-focused and centralized which means morality laws and payment processors can continue to prevent creators from making and earning from their work. There is room for another idea to the mix, accepting cryptocurrency micro-contributions (I wrote about this here before last year’s GitHub Universe: “Take Back Your Blog! Just sprinkle notifications and cryptocurrency…”). Cryptocurrency payments work anywhere in the world, and don’t have the transaction fees of (and cannot be controlled by) credit cards companies. Also, and this can’t be understated, they have the potential to put creators firmly in control of what they have collected and their identity on the net. If you are triggered by “cryptocurrency” forget about the hype and think about the creators!

How do we make it easier for people who read things on the Internet to adapt the content they are reading to their unique experiences?

I was really inspired to read about the Frankenbook which is a derivative work of Frankenstein, produced in part by the MIT Media Lab. They note: “Frankenbook is a collective reading and collaborative annotation experience of the original 1818 text of Frankenstein; or, The Modern Prometheus, by Mary Wollstonecraft Shelley.” Mary Shelley’s work is now in the public domain, which makes remixes like this online book possible (and lots of other wonderful movies and other art as noted in the link).

Expanding on this a bit, what does putting something in the public domain enable? Perfect customization is a one possibility. I recall as I was writing the book, most of the editor’s emails indicated “more callouts!” (“callouts” are numbered sidenotes to the code) I always felt besieged by a train of thoughts saying “But, won’t the more technical people be bored by those?” My editor was probably dealing with their own barrage of thoughts which said “Non technical people won’t understand this without them!” Who is right?

The answer: it depends on who you are in that moment. At the beginning of the book, we thought it would be interesting to make this a book that offered a variety of languages in the form of projects for each facet of the API. You can find a section on Commit Status API using DotNet, Search API using Python, Gollum Wikis with Ruby, the Pull Requests using JavaScript (via AngularJS), and writing to the Git Data API on Android in Java. The unfortunate side effect of this choice meant that each chapter had to have an entirely different set of instructions on setting up the language tools, and this probably placed an unreasonable burden on even the most enthusiastic and energetic readers. It was probably even worse if you happened to know some of the languages already. Obviously there is no way to skim to the right place in a printed book and skip the sections you aren’t interested in. We probably lost crucial attention from this choice, and lost readers as well. When the user has full control over makes things more interesting. Right now on the experimental version of the book site https://btwg2.teddyhyde.io you can see an example of a dialog that allows you to turn off setup instructions and minimize callouts if that helps you learn. What about taking the callouts and turn them into a quiz automatically? Making a book suit you (especially if those needs were different at different parts of the day) would go a long way to making it more readable for everyone.

How do we make it easier for people who are reading to offer their comments and suggestions?

People are not really reading books, not as printed versions, nor as PDFs on their desktops. They are “reading things” on their phones. If you want to have your readers provide comments and suggestions, you need to meet them with technology that works on their phones. This is not always the case with online media that often seems tailored only to consuming media, not helping to make it, which is a huge loss.

GitHub is, of course, a fantastic way to facilitate collaboration, and those tools can extend way beyond just coding projects. But, developers (and authors for sure) don’t reach first for their mobile phone when they want to access GitHub. This is one reason I built Teddy Hyde (the no compromise, extensible, one-handed Jekyll blog editor for Android), to make an ergonomic and pleasurable experience for editing blogs hosted on GitHub. We can go further. If GitHub is just used to verify your identity, but there is “zero UI” for adding your comments or suggestions, would that make it easier? Well, head over to https://btwg2.teddyhyde.io to add a comment and try it out. Click on the pencil icon at the top right and add your comment!

As a side note, I could really use some help understanding what needs to be in place when we accept contributions through GitHub. Is a CLA the only choice? Should I care about copyright over collaboration? If you have expertise as an author, please don’t hesitate to reach out ([email protected])!

blog comments powered by Disqus