Why it is too hard to learn new coding tools

Today I was trying to learn TensorBoard, a way to visualize the inner workings of neural nets built by the same folks at Google who built TensorFlow. As with any new coding library or tool, the best way to learn is to find a working example, and then take it apart, line by line, and understand what each line is doing.

I was following along with a YouTube video, as a Google engineer went line-by-line through an example with TensorBoard. At the end of setting up the neural net, he wrote one critical line that set up the “TensorBoard” part of the code:

tensorboard --logdir /tmp/mnist_demo/1

However, when I ran this line, exactly as he had done in the video, and then navigated to port 6006, exactly as he explained, I got this:

Instead of this, which is what I expected based on the engineer’s video:

Now, I’m a competent software engineer; I work full-time as a data scientist, and when someone explains to me the exact steps needed to complete something technical, I can usually figure out what they mean, even if a couple of their instructions are slightly off. And indeed, in this case, I did. The Google engineer’s code worked if and only if the user was running their code from their home directory. I figured this out after a few minutes, and fixed the line to be this:

tensorboard --logdir ./tmp/mnist_demo/1

But, someone without my skills would have been completely stuck. They would have had no idea how to use TensorBoard, and worse, they would have felt discouraged from trying to learn new things like this in the future.

The point is this: if a novice is going through a tutorial like this one, and there is even one step the requires above-novice-level software engineering to debug, as this Google engineer’s tutorial did, then despite all the other good aspects of the tutorial, novices will be completely unable to reproduce it and thus learn from it.

To solve this: experts must put themselves in the shoes of people who know less than them when writing tutorials. It is well-intentioned but flawed tutorials like this that discourage self teachers from continuing to learn

You might say that the people who make these videos have no incentive to clean up them up and make sure everything is clear. I disagree; the small mistakes in this video (and there are several other similar mistakes in addition to the one I pointed out above) is why this talk will likely garner around 50,000 views, rather than 500,000 —not good news if this engineer wants to get a reputation as a good instructor

Indeed, the YouTube star Siraj Raval illustrates this point: he has built a great following (and is teaching a very good Nanodegree with Udacity) teaching subjects such as Deep Learning using meme-filled and often silly videos in quite literally a “hand-wavy” fashion. Nevertheless, he always accompanies his videos with working, well-structured coding examples that you can clone down from GitHub, pick apart, and start learning from quickly. That is why people are learning Deep Learning from Siraj’s YouTube channel, rather than from the more rigorous but also often incomplete (in the sense described above) videos on the Google Developers channel.

It shouldn’t be this hard to learn new coding tools. We could always throw our hands up in the air and say “Tough, learning new things is hard.” We shouldn’t do this: the internet has the potential to put the best tools for adding value to the world through building software in the hands of billions of people, and whether or not the people building those tools take it upon themselves to explain what they’re doing clearly will be the difference between thousands and millions being able to follow in their footsteps. Or, maybe Siraj will do it all for us.

To see a cleaned up version of the TensorBoard walkthrough in the video above — along with an example pulled from Siraj’s GitHub — see the TensorBoard folder on my GitHub.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.