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

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

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

You are commenting using your 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 )

Connecting to %s