The Art of the Coding Tutorial

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

  1. We want them to be as easy to follow as possible for developers of all skill levels.
  2. 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.
  3. 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:

  1. What are some examples of tutorials that you have found effective?
  2. 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.
  3. Is it more important to get to Point B, or understand *how* you got there?

5 thoughts on “The Art of the Coding Tutorial

  1. 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.

  2. 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.

  3. 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

  4. 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.

  5. 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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s