Written by Creative Strategy, UX Design

Is Troubleshooting Dead?

The UX of an outdated tutorial can be both a missed opportunity and a chance for students to teach themselves vital problems solving skills.

Is Troubleshooting Dead?

The Lost Art of Hacking

Few paying customers believe that struggling with an out-of-date tutorial is a blessing.

Students these days — young and old — expect to pay for an online tutorial, learn a specific skill from an expert, and have ZERO friction. When they discover a particularly popular instructor (e.g. Code with Mosh), they see a whole catalog of tutorials they can learn at once. A one-year subscription gets you what is essentially a personal tour of the skills needed to become a good Front-End Developer. 

Unfortunately, there’s a catch — many of Mosh’s tutorials are outdated. Can you still use them? Yes! Absolutely. All of his tutorials from HTML/CSS and JavaScript to React and Node are excellent. However, there are parts that are no longer valid. It is these courses that provide an unintended lesson that most students overlook: Troubleshooting.

This is a big user experience (UX) reality check because it begs this question:

Is a tutorial suppose to give you a frictionless user experience or is it suppose to teach you how to think for yourself?

Let’s explore this for a moment by taking on two particular personas:

Just Tell Me Tom
Attributes: Built a webpage for a friend once
Desires: Needs to learn the basics to get a better job
Behaviors: Only wants the answers, easily frustrated
Quote: “Don’t make me think.” 

Lifetime Learner Leo
Attributes: Everything he knows has expired
Desires: Needs to refresh his skills to get a better job
Behaviors: Can’t move forward until he solves the puzzle
Quote: “There is more than one way to do anything.” 

Planet of the Code Monkeys

Many students looking to become a Front-End Developer think that a tutorial is designed to be frictionless. This is the case for Just Tell Me Tom. He expects the answers, simple examples, and constant feedback from the instructor. But what does this actually teach Tom? Some would call this teaching model the “Code Monkey” process. This is where Tom is following along with the instructor and watching the code being written on the screen. Then Tom repeats the same code in his editor and gets the same result. This shows him instant success and makes him continue with the course until he’s completed it.

With his certificate in hand, Tom is now ready to apply for that new web developer position and pass that coding test. It won’t be long now until he lands the job and magically becomes a developer.

But Tom has a problem. The process of imitating the behavior of a developer does not make Tom a developer. Because when it comes to the coding test and/or interview, Tom is presented with challenges that look nothing like the examples in the courses he took. The first time Tom experiences conditions or scenarios that don’t match his carefully crafted examples, he chokes.

Welcome to real-life development, Tom. This is the dark side to becoming a code monkey.

What Tom didn’t (or wasn’t) prepared for was the debut of his own Simian Army. Better known as the principle of chaos monkies or chaos engineering, this is where things go wrong all the time — often by design.

Tom? Allow me to introduce you to your personal chaos monkey, Mr. Muphy of Murphy’s Law fame. I think you two will be very good friends for a while!

Newly minted code monkeys like Tom, don’t have any experience with troubleshooting because they’ve always had the answers given to them. Nobody has ever thrown a wrench into their code and forced them to figure it out. The end result is a student who has become befuddled (Yup. That’s a real word. Go look it up!). Or in the words of comedian Brad Upton, “…they look like they’ve been hit by a shovel!” Poor Tom.

Raider of the Lost Puzzle Palace

On the other side of this equation is Lifetime Learner Leo.

Leo used to know all this stuff “back in the day” but is having to start back a square one. However, what Leo lacks in modern web development skills he more than makes for in something called the scientific method. Leo knows how to make observations, form questions, test out possible explanations, and systematically find solutions to all kinds of puzzles. Web development bugs are no different. Each one creates a problem, has interesting outputs or errors, and can be work through using tests and deduction.

In other words, Leo knows how to troubleshoot. In fact, the puzzle IS the reason he loves technology in the first place.

When Leo approached the challenge of becoming a Front-End Developer, he sees a tutorial as a doorway into a new world. He expects there to be answers and examples but is not expecting the instructor to just hand it to him on a silver platter. The first time the tutorial doesn’t make sense or is using outdated examples, Leo starts to dig. He might even ask himself, “How could I make this work using the latest version?” It might take Leo a day or even a week to figure out why the example didn’t work as shown or why the version of the code Leo is using is no longer used in that way. He knows that software dependencies are growing and changing all the time and is well aware of how quickly the latest and greatest can become a dinosaur. He’s lived that reality and has become accustomed to searching for answers in all sorts of ways.

It may take Leo three times longer to finish the course than others but he will finish it with everything working — one way or another.

With his certificate in hand, Leo is now ready to apply for that new web developer position and pass that coding test, just like Tom. He also feels that it won’t be long until he lands the job and magically becomes a developer.

Leo, however, has an advantage over Tom. The process of grinding out a problem until a solution is discovered — or a workaround — is a behavior that every developer needs. Seth Godin calls it Poke The Box where he states, “Your position in the world is defined by what you instigate, how you provoke, and what you learn from the events you cause.”

This way of thinking doesn’t make the coding test and/or interview any easier for Leo — he is a newbie after all — but it does give him an arsenal of thinking strategies for solving problems. When presented with challenges that look nothing like the examples in the courses he took, Leo has the capability to adapt and attack them from multiple angles. Even when Leo experiences conditions or scenarios that don’t match anything he’s ever seen, he knows how to start chipping away to find a possible solution. Leo isn’t fast, but he’s smart. He won’t set any speed records for code challenges but he will find the answer.

Employers worth their salt should know the difference between a Just Tell Me Tom and a Lifetime Learner Leo. 

The Bane of Evergreen Tutorials

Now that we’ve played around with the personas of Tom and Leo, I want to reiterate the UX question we started with :

Is a tutorial suppose to give you a frictionless user experience or is it suppose to teach you how to think for yourself?

For those out there that create tutorials, I’m afraid the answer is a double-edged sword.

Yes, you want to create the most up-to-date, accurate, and frictionless tutorial UX possible. You want students to learn, complete the course, and then tell all their friends. That’s the reason you created the course in the first place, right?

Yet, there is another part of you that doesn’t want to create a Simian Army of poorly trained code monkeys that only copy what you teach them, don’t put much effort into learning beyond the tutorial, then complain when they can’t use what you taught them to get a job. Or worse, have them tell your industry peers (and their friends) how much “your course sucks” because they couldn’t make it work in their best interests. 

What’s a tutorial creator to do?

First, I’m afraid you’re going to have to grow some thicker skin in the long run. Not everyone is going to put in the effort to learn what you’re teaching. There will always be Toms. They’re like the students you, unfortunately, got paired with for important school projects. They never do any of the work but always want the credit. Everyone wants a shortcut that doesn’t exist. These people are your Toms. 

Second, you’re also going to have to be a good steward of your content. As an instructor, you have to — you need to — stay vigilant about dependency changes that wreck the flow of your course. This is because there is a silent third persona that we didn’t really get into: Confused Cathy.

Confused Cathy is very interested in learning the content but because you didn’t take the time to update your course, she’s now completely lost. Chances are, if a solution is not found anytime soon, she will just stop the course and never come back. When you ignore (or abandon) your evergreen course feedback, these are the people that you never hear from. Toms will let you know. Toms will let EVERYONE know! Cathys might never let you know. They’re too nice. Unfortunately, Cathys who never hear from you will not come back nor will they recommend you to their friends.

Herein lies the danger. No one really listens to Toms. Everyone listens to Cathys. 

Third, and most importantly, if you’re teaching anything that involves technology, you need to create your own Simian Army style by weaving chaos engineering examples into your courses. Leos will find a way to make your outdated courses work but it will severely impact their progress.

Meanwhile, Toms will get a little taste of troubleshooting that might help them learn more than they wanted to know. By included worst-case and edge-case scenarios in your course, you can dramatically improve the quality of the lesson while teaching students how to problem-solve. They might still behave like code monkeys but the more your challenge their ability to respond to problems, the better they might become in solving new problems on their own.

It would behoove you to attempt to teach Toms and Cathys how to think like Leos.

Everyone Wants to Eat… Few Will Hunt

If you want to teach high-end skills that students will base a career on, then you’re going to need to improve the UX of your course to include troubleshooting techniques. As an instructor, you can no longer just get your students to the water. You need to help them understand a few different ways to drink it.

The same goes for students. The old adage that talks about “you get what you put in” is very true when learning how to troubleshoot tutorials that are out-of-date. YOU have to learn how to drink! And by drinking (i.e. learning to troubleshoot using tools like the scientific method or chaos monkey thinking) I mean making it your personal responsibility to figure out HOW you can make an old tutorial work with current technologies. You need to dig into the logs, understand the errors, know what changed in the dependencies, learn how to develop a workaround, and MOVE FORWARD!

A student that can figure out the bugs in an outdated tutorial by using Google Search, reading blog posts, using Stack Overflow hints, digging through documentation, and asking questions, will become ten times more useful than any code monkey or certificate holder. And the reason is simple: real-life requires you to develop these skills. Nobody in your next job is going to show you the answer.


If you can’t troubleshoot, you’re not going to last long. And a tutorial can only take you so far. This means you have to pursue these skills yourself. It is a skill that can be taught, not unlike the scientific method, which is why I believe your mandate, as a student, is to not let a problem in a tutorial stop you from learning.

Mosh will update his tutorials someday. I’m sure of it.

However, until he does, you need to use these kinds of problems as an opportunity to figure out the puzzle yourself. The lesson you teach yourself about troubleshooting could make the difference between a good job and a great one.   

Remember, everyone wants to eat. Few will hunt. Be a hunter.

#ux #troubleshooting #chaosengineering #teaching

Photo by Flash Dantz on Unsplash