WIwiseleo·Jan 20, 2019
Good question. I struggled when I wanted to try some API sample code and I had to start by configuring Yeoman, brew, and whatever other infrastructure just to get to the point of being able to run a "simple" sample.
I have also been to 4hr workshops where 3 hours was taken to help students get setup with whatever environment we were there to learn. It would have been trivial to setup remote VMs.
An even more interesting question is how to keep tutorials executable as the underlying technologies evolve. This is a big problem with older books where code doesn't even compile. Microsoft Press is especially notorious for this.
I agree that combining technologies does not make sense. There is one very good approach I've seen used by the Meteor book team. I will use the same approach for writing tutorials for my technology.
The entire book is va
Read the rest
lid Meteor code. As it evolved and broke compatibility between 0.8 and 0.9, the book became outdated. However, the team continued to evolve the code.
Their approach was centered on checking out the next branch instead of typing it manually as you read. As you start reading next code listing, you can type "git checkout chapter4-1", for example. So, as the code would evolve and no longer function with latest version of the framework, they would update the branch tag and it would magically work again.
Although the code hasn't been updated since 2017, you may find it very interesting. If you run it with that era's Meteor, it will still work despite the code being largely irrelevant today https://github.com/DiscoverMeteor/Microscope and the http://discovermeteor.com site explains its rationale to end their involvement in the project.
One of my pet projects is to fully explain how to implement oAuth. If you can fully understand how to implement Salesforce login, others are cakewalk because they mostly omit steps that Salesforce chose to implement. I have a few ideas how to do it, but it may be a challenging task. Still, it's the most sticking point I see for newer developers who want to deploy usable code. It starts with calculating base64 header values and then they throw digital signatures and expiring tokens at you. In other words, have fun interpreting this tutorial. ;) https://developer.salesforce.com/docs/atlas.en-us.api_rest.m... It tells you what it expects but not why it expects it.
Twilio explains it fairly well, but expects you to implement itself using its SDK.
My intent is to build a comprehensive site that supports multiple languages to implement oAuth starting with plain JavaScript and a handful of select platforms and then adding support for other languages to get to the point where official documentation finally makes sense.