JEFF BLANKENBURG

Random geekery since 2005.

Husband, father, programmer, speaker, writer, blogger, podcaster, collector, traveler, golfer.

The Art of the Coding Tutorial

Written in

February 8, 2017

jeffblankenburg

As part of my new responsibilities at Amazon, I’m working to re-write the Alexa development tutorials for a couple of reasons:

We want them to be as easy to follow as possible for developers of all skill levels.
The Amazon Developer Portal and AWS will forever be making changes to their interfaces, and we want to be able to easily keep up with updating our screenshots.
We want to be able to re-use as much of each tutorial as possible, again to minimize the maintenance costs that come with updates.

Before anything else, however, we want tutorials that help developers get from Point A (no Alexa skill) to Point B (published Alexa skill) with as few barriers as possible.

So I ask these questions of you, my wonderful readers:

What are some examples of tutorials that you have found effective?
Which is the best format for you to follow a tutorial?
1. One long web page that covers every step.
2. One web page that covers the essential steps, but has links to the “fringe-y” stuff that only some developers will require.
3. Multi-page tutorial that breaks the process into 5-6 digestible chunks.
4. A video.
Is it more important to get to Point B, or understand *how* you got there?

5 responses to “The Art of the Coding Tutorial”

mattsonlyattack

February 8, 2017

A series of shorter videos that you can more easily replace with updated content seems like a good path. https://egghead.io/ is putting out solid content that way.

Reply
Dennis Burton

February 8, 2017

Being a bit partial, I loved the flow of ChooseYourOwnApplication. I can see a set of tutorials on a ChooseYourOwnAlexa path that allows you to get to an endpoint application by choosing the next topic of interest. Add in the concept of achievements and you find users exploring paths they might not have otherwise.

Reply
Jon Kruger

February 9, 2017

I’m really starting to like screencasts. It’s so nice to have a person explain what you’re doing. It feels way less overwhelming then reading lines and lines of code. These Redux tutorials are great, they are short and they take a very step by step approach. https://egghead.io/courses/getting-started-with-redux

Reply
Pete Shearer

February 15, 2017

I also previously would have said short tutorials (option 3), but I’ve found that well done screencasts just can’t be beat. That being said, chunking those and putting them in a playlist (so out of date pieces are more easily replaced) makes more sense than just throwing an hour-long tutorial my way.

Reply
Steve Tingiris

February 24, 2017

Three our of four respondents here prefer screencasts / videos. I’m going to make it four out of five. When it comes to coding tutorials, it’s hard to beat a screencast in my opinion. So, +1 for screencasts.

Reply