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.

skrollr.js

First I wanted a project that well utilized Parallax scrolling using JavaScript and Cascading Style Sheets (CSS). I did a whole lot of research and ended up with Skrollr.js tool Very nicely done, pretty mature product, seems continuously monitored with frequently updates. Very detailed product with a whole lot of content. Somebody spent a lot of time putting that tool together. When I first say the Behind-the-Scenes-at-the-Walking-Dead site I was hooked. In fact that walking dead site came with a very nicely written tutorial. (Kudos to Elli Bishop for that tutorial submission). Skrollr.js sounds like a great tool with lots of capabilities, unfortunately using the tool proved way difficult. I’m not saying it was without documentation or available tutorials, but the skrollr tool had obviously gone thru numerous design changes and improvements. Unfortunately it wasn’t always clear on which tutorial focused on which version of skrollr was being discussed. The other thing, at least for the github tutorials, there were numerous files involved, and those created a whole lot of confusion. In this case, I’m referring to the CSS files. For skrollr, CSS is a major big deal. The problem was these CSS files were quite large, and it was nearly impossible to figure out which CSS lines supported the tutorial specific concept being illustrated. The documents weren’t so helpful either. You got the distinctive impression that folks built supporting tutorials and documentation, but no old stuff was EVER deleted, and nobody would tell you what’s new and what’s old. I wasted a whole lot of time there.

jsPDF

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.

Recommendation

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!