How to Make Web Tutorials Last Over Time

May 22, 2016

Let's make articles age well and avoid web rot

We all struggle to stay on top of the latest trends. There is no shortage of quick tips, deep dives, getting started posts. Hell, there are even more options when you include videos. Some articles age well over time, but sadly, most do not.

I’ve gone through countless TutsPlus, Treehouse and other tutorials where I get stuck halfway in due to a breaking change in a framework or package and I’m not sure what version I’m supposed to be using or what to do to fix it. There’s nothing that frustrates me more than paying for a membership to one of these sites and you’re unable to complete the course. The communities and forums attached to their courses are often filled with unanswered questions of (paying) users who have come across issues with the material.

While we all learn differently, I’ve come to find that there are some universal principles all tutorial authors should follow:

  • Explicitly state which version numbers you’re using when installing packages.
  • Provide a package.json file or starter files.
  • Never paste large blocks of code. Type it all out and break it up into smaller chunks and explain whats happening bit by bit.
  • Make lots of CodePens!
  • Leave in slip ups and debugging of errors. It shows you’re human and also how to troubleshoot a problem.
  • Avoid saying “just”