Answer these four questions, get a free book
Four thoughts for Internet creators, as we release our book to Creative Commons
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:
- Is the “book form” narrative still relevant (especially for technical content like the material covered in this book)?
- How do we compensate creators on the Internet, again, especially when their work is in book form?
- 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?
- 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?
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@example.com)!
blog comments powered by Disqus