Thoughts on What Makes a Good Tutorial for A Software Tool
Not sure why I keep falling into this trap, lately but its driving me crazy. I’ve been working on a couple of projects lately where I’ve searched for a software support tool, only to be hugely frustrated by the help tutorials (or lack thereof) and by really poor How-to documentation. As a result, I think I’ve come up with an easily describable spec for a how-to tutorials.
For the next project I was working on (Tabbed Tube Notcher), I needed the ability to convert displayed lines in html5 canvas over to paper with absolute control on perfect sizing. I discovered the library jsPDF Way cool, but wow is the documentation mediocre. The final kick for me was the discovery of this tutorial link. I loved this sentence in the top of that article:
Unfortunately, the documentation for the library is poor, so we will describe most important APIs.
So with that I’m thinking, way cool, here we go, they agree with me the documentation for jsPDF is poor. Now we’re going to get somewhere! So I’m going thru the code, and what the heck? They offered this way odd file Tizen input/output tooling within the code. It wasn’t clear what the code did, what an appropriate workaround was, but clearly the code as written failed miserably. Ugh. How can you complain about the other guy then offer up this dysfunctional tutorial?
And then I stumbled upon an other aspect of jsPDF and that is integrating jsPDF with the HTML2canvas tool. I found this stackoverflow question/answer and wow, the user Blizzard totally nailed it. Simple answer accompanied with a very functional jsFiddle, all code visible, all code functional, with implementation upon click(). Yes, that’s how it should be done.
So, for software API tutorial / documentation examples, the best responses should:
- Fit into a single jsFiddle (with code, CSS, HTML and dependencies). You can see what supports what on a single page without crazy flipping from one file to another.
- Be functional. The jsFiddle works without error.
- Is simple enough to show one concept per jsFiddle example.
- Is without unnecessary code that distracts the developer from an effective learning process.
- Is documented with accurate dates / version levels so folks know what’s what and why in the future
So now, I’m thinking my best course of action it to put my money where my big mouth is, and recommend / create a jsFiddle or two in support of these open source projects!