Why Your API Fails

by Michael James Williams on July 29, 2009 · 7 comments

in Articles

Your API fails when you focus on making it simple to use the second time, rather than the first.

Life is too short for man pages, but occasionally much too short without them.

I’ve been getting emails asking for help with implementing various APIs. Mochi and Facebook are the most requested, unsurprisingly.

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.

{ 7 comments… read them below or add one }

Scarybug July 29, 2009 at 8:41 pm

Nail on the head.

Though I had very little trouble with the mochi leaderboard API, I just attached it to its own little movieclip instead of the stage so the play call didn’t do anything. I did find that to be a baffling “feature” why not just throw a custom event when you close the score and let the dev decide what, if anything, to do when that happens?

Still, it’s one of the easiest to use APIs I’ve worked with.

Michael Williams July 29, 2009 at 11:43 pm

Cheers :)

Yeah aside from that (good idea with the event by the way, much more intuitive), I found the Mochi API to be very simple to use. It’s hard to pick a widely-used API with terrible instructions, because they tend to, well, fail ;)

kegogrog July 30, 2009 at 9:23 am

That’s exactly what I did. I created a dynamic MovieClip to hold the leaderboard and to the showLeaderBoard function I added an override of the onClose. I added an EventListener with MouseEvent.CLICK to the dynamic MovieClip. Just because the dynamic mc also shows the actual score and the saved score from local Object. Clicked away it restarts with the TitleScreen.

kegogrog July 30, 2009 at 7:02 pm

Sorry for the second comment. Here is my example of a highscore screen class:
http://blog.natan.info/2009/07/30/as3-mochiads-leaderboard-with-custom-onclose-function/
or in short just the custom function:

MochiScores.showLeaderboard({boardID: boardID, score: endScore, onClose: function(){root.screenHisc.addEventListener(MouseEvent.CLICK, clipRef.restartGame, false, 0, true);Mouse.hide();root.cursor.visible = true;}});}

Regards and thanks for that comment on the help screen topic (I just assumed too much simplicity…)

Michael Williams July 30, 2009 at 10:38 pm

Neat solution, thanks for that. And that blog post is good too — somewhere to send people who are confused!

Leave a Comment

Writing code? Write <pre> at the start and </pre> at the end to keep it looking neat.

Anti-Spam Protection by WP-SpamFree

Previous post:

Next post: