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 itch.io 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 itch.io 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.
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.
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.
Global 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):
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.
You May Also Like
