Simple APIs are good for experts as well as beginners

A couple of commenters on my previous post felt the Game Studio API is already sufficiently easy to learn (thanks guys!), and pointed out that we can never hope to make it easy enough for everyone.

True that. The sarcastic British part of me wants to say something like "why even bother trying to help people who are too stupid and lazy to read the docs first?"

But then the lovey-dovey hippie part of me has to counter "remember, we were all foolish beginners once. Helping kids learn to program is super important if we want a healthy supply of experts in the future. Plus, it's just nice to help people, even if they do sometimes ask annoying repetitive questions. Group hug, everyone!"

Confession: I consider myself an expert programmer, and I know how to use a search engine, but I don't like to read docs. First, I try to solve most problems with a combination of guesswork, IntelliSense, and vague memories of an API I last used six months ago. If that doesn't work, I'll go do some reading, while thinking "stupid confusing API, wasting my time by not working the way I expected".

As a framework designer, part of my job is to increase how often things just work the way you guys expect them to.

Thought: for every hundred people who get stuck and ask a question on the forums, there are probably ten thousand who had the exact same problem, but knew how to use a search engine to answer it for themselves. If we could eliminate the source of the problem, that saves five minutes of reading for ten thousand people, which is a whole month!

Thought: in a world of ever increasing complexity, it is not possible to be expert in everything. Being an expert is hard work. You have to read manuals, subscribe to blogs, go to conferences, and somehow remember all the resulting information (if you are reading this, congratulations: you're already taking steps along the becoming-expert-in-XNA path.

I use System.IO and System.Xml pretty often, but never had the time or interest to become truly expert in them. The more intuitive an API, the more quickly a non-expert can solve their problem, without having to waste time and fill up limited brain space gathering knowledge from outside their core specialty. Should a network programmer have to become a graphics expert in order to render debug text to the screen? I think not.

As a framework designer, part of my job is to increase how often people can be productive even when working outside their areas of expertise.

Comments (18)

  1. David Black says:

    Perhaps an even more important consideration is the case where someone thinks an API works in a particular way, they write code that appears to work. But unknowingly introduce bugs and have to pay the cost of finding those bugs later on.

    This I think is the true power of XNA (and C#/.NET style things in general).

  2. I really applaud you for taking this attitude! I consider it very helpful to have API as "idiot proof" as possible. I’m really grateful that XNA has so much abstracted in a clear manner it makes it a lot easier on us independent developers trying to create games on our own or in very small groups.

    I’m also glad that there is enough low level access that the intrepid expert programmer can dig in and achieve almost anything they can imagine. Finding that balance has got to be a huge task for you guys and I’m thankful that you are there making the tools that much better for the rest of us mere mortals!

  3. Casey Thurston says:

    Certain concepts will always be more accessible than others to beginners (especially as game development is such a multidisciplinary field), but since working with XNA I’ve never once found myself stumped. There’s always been a relevant sample, blog post, or forum post available… once my coder’s ego gets out of the way, that is.

    You hit the crux of the issue with your second thought: there’s simply too much information out there to become an expert on everything. It follows that part of becoming an expert is learning how and when to go digging around the interwebs for help. Yes, the API should be intuitive where reasonable–where there’s industry- or community-wide consensus for example–but pandering to a user base that won’t leverage the wealth of educational materials available does a disservice to those users (who will never learn how to walk on their own), other users who have put the time in (and want to see improvements to features rather than usability), and yourselves (because you’re spending time refactoring that could be invested pursuing exciting new avenues). Sometimes you just have to say [url][/url].

    I hope, somewhere, Jim Perry is nodding sagely.

    I do suggest two minor changes. First, a modification to the forums to advertise the search functionality a bit more aggressively (maybe return relevant samples at the top of the search as well). Second, our community probably has the critical mass to support a Wiki page, which could be a valuable resource and take some of the load off of the MVPs. Personally I think you guys have done an amazing job with XNA and I’m excited to see how it evolves (especially with the Windows 7 Phone and its Live functionality on the horizon). Many thanks!

    P.S: I must second the sentiment of David Black’s comment. I still have nightmares about the STL map and its wonky implicit addition behavior. I don’t know whose idea that was but past-Casey wanted to throttle them right up to the day .NET generics rendered STL personally


  4. Daaark says:

    This post is reminding me of all the SpriteBatch renderstate issues that new users bump into.

  5. Jon Watte says:

    "idiot proof" and "simple" are very different goals.

    The C library function "realloc()" is simple (a memory manager in a box!) but nowhere near idiot-proof.

  6. Peter Leahy says:

    Well said.

    Keep it up, you guys have done an awesome job so far wrapping up something as inherently broad/flexible/random as game development into a framework where you can "follow your nose" through.

  7. Cardin says:

    Simplicity and complexity is a difficult thing to balance. I applaud you in trying to strive for the best of both worlds. =D

  8. I too am a live-by-intellisense developer. If I can’t find my way through intellisense or hitting F1 on a class and finding a useable sample that I can manipulate for my purpose I feel left out in the cold and go foraging on a search engine for a while. Sometimes I’ll eventually pick up a book but by then it’s often all to late and I’ve already decided to shelve the implementation approach I was facing with for some other alternative 🙂

  9. RBGKnights says:

    “Simplicity and complexity is a difficult thing to balance.” – I think this statement is incorrect! If you put Simplicity and complexity on the same scale it can be hard to find a balance. But that is often why I don’t put them on the same scale.

    Simplicity to me is how easy I understand something. The SpriteBatch is a good example I add some textures at a location and they are drawn at that location. On the other hand you have something like Render States. (This scares the hell out of new XNA programmers. What properties do I need to set, when and where?)

    Complexity to me is how the how much the system can handle. The overwhelm nature of complexity can be hidden by Appling Design patterns to make that complexity easier to use. (Again the SpriteBatch comes to mine!)

    I believe the guys on the XNA team have done a great job of making something very complex approachable and fun which is really the best you can hope to do.

    That’s not to say I would not change anything in the framework. I have created a library I use in all my games that extends the XNA adding things like GUIs, lighting rigs, terrain, etc. I think the one thing the team can do is continue to produce great samples.

  10. Balogh Attila says:

    The best thing about XNA is that it fired up the game creator community.

    The fact that there are a lot of people asking basic questions just assures that XNA is easy enough for somebody with basic programing skills to not get scared and try it out.

    But here lies a problem. I agree with you Shawn that we all were beginners once but then again we didn’t wanted to write games before we could manipulate data types or have some basic math knowledge or application design knowledges.

    Most of the times i still write games in MDX at work and if you would get a penny every time i say "Man i wish i would have to solve that issue in XNA" … 🙂 you get the point.

    Anyway what i would like is a not MSDN style documentation cuz i don’t find MSDN useful most of the time so i end up googleing (which always helps me).

    And i would like to run my XNA game in an easy way to have a borderless window if that would be possible on Windows (there is a reason why i would like this but its too long for me to detail it here).

    Thanks for all the good work and for all the times i enjoyed making my games.

  11. DragonSix says:

    Most beginners expect an engine when it’s an API. That’s where the confusion is, mostly.

    Maybe someday some developer will finish a nice user-friendly engine for them. But that’s a completely different topic.

    As an API the current XNA accessibility is quite excellent already, don’t forget about improving other things too.

  12. MasterX says:

    I think the main problem of XNA is the documentation, it’s written by a software engineer not an instructor or someone with some teaching skill (no offense intended, it’s probably crystal clear for veteran programmers), if any first-timer tried his luck reading it, he’d end up wasting at least 30 minutes to first find what he’s looking for, then understanding what the the one who wrote the documentation was trying to explain.The easy way out ?, the forums of course.

    If you have used any software by Autodesk (specially 3Ds Max) you probably have a good idea how a great documentation is written.

  13. Orin Tresnjak says:

    On the one hand, this attitude is really what makes XNA so great.  Almost all of the time, things just WORK as I’d expect them to, and Intellisense alone is enough to figure out what I need.  It’s DirectX with all the tricky yet unimportant details hidden behind an intuitive facade, and yet it’s versatile enough to (usually) satisfy this professional game developer.  I use it for all my hobby projects now and often find myself wishing I could use it at work. 🙂

    On the other, the documentation is a major barrier to learning.  The docs mostly seem to follow the MSDN style of:

    Function Foo::Bar()  Does Bar on object Foo.

    …rather than explaining why you would want to do Bar to Foo and what sorts of things you could do use the Bar functionality for.  This style is useless to the beginner and not that helpful to the pro either.

    I absolutely agree with MasterX–the 3ds Max documentation would be a great model.

  14. Byron Nelson says:

    "As a framework designer, part of my job is to increase how often people can be productive even when working outside their areas of expertise."

    As far as I am concerned, you have done that part of your job perfectly. Computer programming is a tool for me, & far from my "expert" comfort area.  With XNA I’ve been able to accomplish things I have wanted to do for over 15 years, but been unable to devote the necessary time to learn and use the tech of the time.

  15. Mike Streatfield says:

    To me, a good API expresses a series of concepts in terms of nouns (data types) and verbs (methods) in a way that doesn’t overload any of those concepts unnecessarily. What that means is that when you’re using the API you don’t need to think so much about the syntax and building blocks you’re using to solve the problem as the problem itself, although that of course partially depends on the language too. I think the hardest part of designing an API is providing a narrow enough interface for people to reason about at higher levels rather than just blithely exposing everything at the same level.

    Jon: Specifically, I think C’s realloc is an example of a really bad API because it does many things in potentially many different ways, which makes it both complex to document and hard to use because you have to think about reshaping the block before dropping it in the hole. In contrast, the pair of functions malloc/free both do one thing and one thing well, so you can think about the fact that you need the memory rather than how you’re going to get it.

    Just for Shawn: this is something I learned early in my programming career and the reason I still use Allegro to get little things done today 🙂

  16. Adam Miles says:

    While I largely agree with the ideas of the post I think the XNA Framework focuses too squarely on being a cross-platform API whereby the process of porting from one platform to another is simply a case of pressing F7.

    In doing that you have to hide/lockdown certain interesting areas of the 360 that might otherwise really help people make better looking games. Array textures (less draw calls), depth stencil as texture (lots of graphical techniques), control over EDRAM allocation / predicated tiling (HDR), tessellation… the list goes on. This has led to one of the most oft-asked questions on the forums: "Why are my RenderTargets purple?", to which the answer a length explanation ensues.

    I think (speculation!) a lot less people will use/maintain two builds of a game than you might think. If someone is a beginner then they’ll likely be developing on PC, if they’re making a DBP/Indie Games game, then they’ll be developing on 360. While the goal of a cross-platform API is admirable and definitely should be the target, I don’t think it should be at the expense of supporting all platforms to their fullest potential.

  17. MrHelmut says:

    I think that an API is easy and simple enough when it fits your mental representation of a problem (e.g. finding the wanted class without formerly knowing it exists in the API just by knowing "it should be here and do this"; guesswork as you said). Even if XNA is simple and will improve, a (possibly large) part of the beginners don’t yet have a good mental representation of how things are working and will always ask questions, no matter how simple an API is (mainly true for complex problem such as the ones covered by XNA). It is a hard to design an API such as XNA and it is quite pleasant to have people thinking like you working on it. I think that it is what makes XNA a successful project: its simplicity. Graphics API really needed it and it opened many doors to many developers.

    So, keep going.

  18. Great post.  I have nothing really to say except that.  You obviously ‘get’ it.  Although I am always discouraged when I see people unable to solve problems because they refuse to do research or stop at the first large bump they have to get over, this doesn’t mean it should be hard to learn to begin with.

Skip to main content