The Tutorial Two Step

A brief discussion on software development tutorials and two ways to make them better.

How many tutorials do you typically review or use when learning a new technology before you have a functional result?  Obviously the answer is that it varies.  You could stumble on a tutorial which provides great detail in all the areas where you need assistance, in which case you’ll get to your goal when you finish the tutorial.  More likely, you’ll need to review more than one to cover all the holes in your knowledge.  This is especially true when every part of your adventure is new.

As 2017 was winding down, I found myself approaching the end of a new game project and was looking to take advantage of the cross-platform capabilities of the Phaser Game Engine by publishing my new game on before turning to mobile releases on iOS and Android.  Since both of my previously released games are iOS only, I was looking with fresh eyes on how to publish a javascript game.

Certainly a javascript game has the advantage of being easy to publish online as a browser game and this can be easily done on or your own website.  I wasn’t looking for a browser game though, I wanted something customers could download and play offline.  While mulling over my options I was listening to some back episodes of Lostcast, and it occurred to me that NW.js just might be the tool I was looking for.

It’s Dangerous To Go Alone

I started where every new adventure starts - Google.  I was surprised to find my first search turned up a bunch of articles from 2014 through 2016, but very little more recent than that (see this list of tutorials which was updated in October 2017).  Software, especially open source software, being what it is I was hoping for something more recent, but despite several re-wordings of my search criteria, I settled for these ‘older’ tutorials.  This was the first tutorial I reviewed and it formed the root of my final solution so I would like to recommend it to anyone.

Training or Education?

After reading several of these guides, I started working through one of them and when I ran into a snag, I switch to another to make a little more progress and then another.  Many of these guides are missing the same couple of attributes which would transform them from the incredible outpouring of kindness that they are into true educational tools.

Verify System ResponseGlobal Installation of nw-builder fails

How do you know if you did it right?  When you’re skilled and know what you’re doing, you simply observe the system to ensure it is doing what you expect it to.  If it isn’t you investigate and make corrections.  When you’re a N00b, this doesn’t work.  

NW.js fails to install when specifying a bad destination

That’s clearly not right, but what SHOULD it have done? What does right look like?

This is where a tutorial can really shine, showing some errors and explaining what causes them and then showing what success looks like (or how to make an error into success):

The Last Tactical Mile

I wanted to publish an NW.js app, so I needed guidance all the way to the finish line.  While a number of the available tutorials talked about using nw-builder to produce an executable file for the various operating systems, none of the had the detail required to get there.  For example, how do you test your Windows executable from your Mac - or vice versa.  I tried using wine (with no luck), then I tried virtualbox (which was quick and easy), and that's how I ended up installing a whole new operating system...  Another example of the final details not well covered - how do you change your app icon from the default NW.js icon?  I used node-icns to get the .icns (macOS) file and png2icons to make the .ico (Windows) file (both details not covered in the tutorials) in order to get the files required to follow the tutorial steps which were covered.  A final example - audio files - I was originally using mp3 files, but Chrome doesn't support them so I had to convert them to .ogg Vorbis files.  Not a difficult step (I used Audacity), but one I wasn't expecting, meaning I had to figure out what the problem was without guidance from someone who already knew the answer.  It is these final steps that turn 'wrapping it up' into a series of trips down the rabbit hole.


The many people producing tutorials and posting them online for free access by N00b's like me are amazing and the whole world benefits from them either through direct use or by using software produced with their guidance.  I hope they keep on producing them.  If these two steps continue to the areas we struggle with, at least we'll have made it this far.

Latest Jobs

Cryptic Studios

Senior Producer

Night School Studio

Los Angeles, CA, USA
Level Designer / Scripter, Games Studio

Fast Travel Games

Hybrid (Stockholm, Sweden)
Social Media / Community Manager
More Jobs   


Explore the
Subscribe to
Follow us

Game Developer Job Board

Game Developer Newsletter


Explore the

Game Developer Job Board

Browse open positions across the game industry or recruit new talent for your studio

Subscribe to

Game Developer Newsletter

Get daily Game Developer top stories every morning straight into your inbox

Follow us


Follow us @gamedevdotcom to stay up-to-date with the latest news & insider information about events & more