Your API fails when you focus on making it simple to use the second time, rather than the first.
One issue that keeps coming up regards both the MochiAds preloader and the Mochi leaderboards widget. By default, each of these run
play() on their container window when they’re finished; if they’ve been added directly to the stage this can lead to some very strange behaviour.
It’s not a difficult issue to solve; you can simply override the default
play() call with an empty function. This solution is in the DevDocs too — and yet, the question keeps appearing over and over again.
A few months ago there was a five-hour speed game development competition over at FlashGameLicense. One of the rules stated that the game had to incorporate the Whirled API. It was really quite incredible to see how irritating many of the developers found this — and these are people who’ll willingly spent five hours of their Saturday writing code for fun!
Now, I’ve made a couple of items in Whirled, so I know that the API isn’t particularly complicated. There are a lot of classes and functions, but they’re all listed and commented in the ASDocs. There are a few things to bear in mind (like that you can’t have any references to the stage), but these are mentioned in the wiki. Still, it took me several frustrating hours to get to grips with the whole thing as well, the first time I used it.
If everything anyone could need to know is in the manual, what’s the problem?
Sometimes the community tries to help developers that are having trouble. Occasionally this takes the form of great tutorial posts. More often, though, it’s forum commenters saying RTFM.
A fair point, since everything is in the documentation. But as Kathy Sierra put it, “if you want them to RTFM, build a better FM”.
It is not good enough just to have all the information available. It is not good enough to expect the user to take on the responsibility of teaching themselves. And it is certainly not good enough to blame the user when they get stuck at the same point as a dozen others.
The Big Guys can get away with it, because everyone wants to put a Mochi leaderboard in their game, or get on Facebook. But if you don’t yet have that fanbase, you need to make it as easy as possible for someone to pick up your tool and do something awesome with it.
Sound familiar? It should do. The same lesson gets hammered into Flash game developers repeatedly: you can’t expect your players to put the same level of effort into learning your game as you did, because they don’t care as much about it as you do. Not yet.