Kathy Sierra's Blog

To API designers/spec developers: pity those of us who have to LEARN this...

There have been some interesting and useful discussions and guidelines on API design from people like Steven Clarke and Bill Venners. And the discussion can get pretty heavy.

But I'll just mention one idea: APIs should not be exempt from fundamental usability principles. I'm coming from the selfish perspective of one who has to actually learn to *use* these things, and, more recently, as someone who has to try to help others do the same. And if for no other reason than to make myself feel better, I'm going to suggest that if you have real trouble working out an API and you're thinking that it REALLY shouldn't be that hard... perhaps it really isn't YOU. So before you start questioning how on earth they ever gave YOU a PhD in astrophysics when you can't even work out one frickin' interface, take a deep cleansing breath and repeat this little positive affirmation: "It's not me. I AM smart. I have the to prove it. But oh what I wouldn't give to wrap my hands around the neck of the one who designed this API..."

It's easy to rail on API designers when you're on the other side, I know. I've personally authored some of the most unreadable and unmaintainable code in the history of software. But at least I have the decency to feel guilty about it, especially after having spent a few years studying usability and learning theory. I don't want to single any group out, but I have to make at least *one* example; it's from the EJB spec (which, don't get me wrong, I LOVE. It's perhaps one of the most reader-friendly specifications to come from Sun).

Usability principal: Things which behave differently should look different.

This is fundamental user interface or product design 101. Humans will assume that if two buttons share the same shape and color, for example, that they'll generally have the same kind of behavior. So product designers are expected to do things like, "Make the navigation buttons look and feel different from the control buttons..." One of the worst violations of this is in products which use the pure evil of "modes". You know what modes are--where a button is overloaded so that in one mode it does THIS but in another mode it does THAT and... Donald Norman (who recently spoke at the Emerging Tech conference) writes fabulous books, at least one of which should be REQUIRED reading for every programmer: "The Design of Everyday Things". He does a great job of letting you off the hook by explaining how it's not your fault you can't work that device, and that product designers are either being lazy or trying too hard to save money by making fewer buttons.

Example API violation: lifecycle callback methods for Entity and Session beans.

When I try to help someone learn EJB, I spend way more time than I should with things like, "What's that? Why is there an unsetEntityContext() for Entity beans but NOT for Session beans? Oh, because you have to have a callback for when the bean instance is being destroyed. What? That's what ejbRemove() is for? Oh, no, that's just for Session beans. With Entity beans, ejbRemove() means "delete from the underlying persistent store", so... since ejbRemove() was given a profoundly different meaning for Entity beans than what it means for Session beans, well, they had to have something else to call when an Entity bean instance is about to die." And then do all that again with ejbCreate(), of course. (And don't forget that both ejbRemove() and ejbCreate() have corresponding methods in the client interfaces... remove() and create(), which also share these differences.)

According to usability fundamentals, giving the Entity bean interface the same methods as the Session bean interface, but giving those methods completely different meanings, adds MUCH more cognitive strain than if developers simply had to learn two totally new method names. You simply can't wrap your brain around learning that a set of methods does one thing for this object, and something drastically different for this other, very closely related, object. In other words, they made ejbRemove() and ejbCreate() use modes! If you're in Entity mode, they mean one thing. If you're in Session mode, something different. Not that we all don't *get it* and remember it, eventually, but it takes longer and we could be doing other more important things. Like skiing.

Again, I feel a little bad picking on this one example from EJB, especially when there are so many other things I really like about that spec. But it's the one that's caused me the most frustration, because I have to go through this process of helping people learn�and then unlearn/relearn�these methods every time I try to teach EJB.

Now, for some APIs it probably is just a question of better docs. But better docs wouldn't help the fundamental problem of something like modes, so better docs isn't the solution for everything.

My suggestion is that each and every programmer be strapped into the Don Norman Appreciation Chair and forced to read "The Design of Everyday Things". It's fun, fascinating, and enlightening. I have a whole book list after that, but I'll save those for later. My goal in life is to make MY life as easy as possible, and I truly believe that if everyone pitches in, you'll really help me out on that. Because unlike so many of you, I am one of those unfortunate souls who is NOT a quick learner. If not for speed dial, I wouldn't be able to call home. Imagine how long it takes me to memorize well-designed and well-named APIs, let alone the truly confusing ones...

Comments

• Take a lesson from Perl
  Perl APIs on CPAN are simple to use because they use sensible default values. For example the API to request web pages from web sites is as simple as including the module and then saying 'GET' followed by the URL.

  There is no requirement to construct a Url object, or specify which port to talk to, or protocol to use. All of that can be overridden but they have sensible defaults that handle 95% of the standard cases. This is how APIs should be written.

  I've always been impressed with the flexibility of Java APIs and their dedication to design patterns. But I have always found even the rudimentary APIs a bear to use.

  Posted by: jherr on February 16, 2004 at 07:59 PM

• well spoken indeed
  "Again, I feel a little bad picking on this one example from EJB, especially when there are so many other things I really like about that spec. But it's the one that's caused me the most frustration, because I have to go through this process of helping people learn�and then unlearn/relearn�these methods every time I try to teach EJB. "

  Don't feel bad picking at faults in an API you love (why btw, do you love EJB?).
  You should be proud that you can see the bad things in something you love and not gloss them over or even pretend they're good things like so many of the zealots do.
  The reverse is also true of course :-)

  Posted by: jwenting on February 16, 2004 at 11:32 PM

• Required Reading
  I like to think having a background in graphic design/information architecture has helped me as an API designer. Such books should be required reading for CS majors.

  Posted by: crazybob on February 17, 2004 at 07:52 AM

• Required Reading
  Absolutely. I think Edward Tufte should be required reading in our industry.

  In fact, I think a broad range of study is worthwhile overall. I've been able to reuse a lot of what I know about woodworking, cooking, origami, and other stuff as part of my software work.

  Though I have to iterate my agreement with you. On a more specific level, understanding the principles of user-oriented design helps greatly when designing a usable API.

  Engineers need to understand that every hour that they spend making an API simpler and easier to use saves many hours for the users of those APIs. And that turns one hour of work into thousands of hours of savings.

  Posted by: jherr on February 17, 2004 at 08:28 AM

• Take a lesson from Perl
  For another example, contrast the Perl modules for sending e-mail with JavaMail. JavaMail may be a more powerful API, but they've made the 90% case awkward in order to support the 10% case.

  Posted by: jimothy on February 17, 2004 at 10:48 AM

• Ivory Tower Syndrome
  I call it all Ivory Tower Syndrome. Take Swing as the worst case. You've got endless flexibility to create as complicated a model as you'd ever want, and can pull, say, JTable values from rdbms', screen-scrapers, rss feeds, even online weather-predicting toasters.

  But to simply have a JTable that self-sorts, a real-world issue, well, you're in big trouble. VB.NET, heck even REALbasic (realsoftware.com) come out of the box with grids that do it, but in Java, you're relearning the quick sort -- or, worse, making do stumbling through reteaching yourself how a bubble sort works b/c "that'd be easier and Moore's Law has caught up with the bubble anyhow".

  API makers need to get out of the Ivory Tower and hit the streets before they're done. Or, if they're *only* on the street (exhibit A: VB6 & Windows.Forms; ever try databinding in VB6? Great for demos, and demos *only*), they could learn to hit the Tower.

  There's no reason for APIs to get in the way of using great objects, and its the job of the API designer to ensure that their objects cater to both the quick hacker and the truely brilliant power user (whose probably helping make the APIs in the first place, at least with Java).

  Posted by: rufwork on February 17, 2004 at 12:40 PM

• Ivory Tower Syndrome
  You don't have to reinvent sorting in Java, it's already done for you. Either Arrays.sort() or Collections.sort() method can be used to implement self-sorting JTable.

  Posted by: slav on February 17, 2004 at 05:23 PM

• Ivory Tower Syndrome
  It's either one of two things. The first is, as you say, Ivory Tower Syndrome. Nobody is taking these APIs into the street for a few tests before they release it to the public.

  The other problem could be addiction to patterns and complexity. I've seen this a few times and it's not a pretty sight. There is a classic page that shows Hello World done with patterns and while it's a riot it is also scary to me because I have seen this before. Engineers are designing for designs sake and putting complexity and flexibility everywhere instead of just where it is needed.

  That being said, I don't know why I am railing against this stuff. The complexity of Java APIs is what is driving people to code generation and sending them to my site and my book. Bwah, hah, hah! Let's hear it for complex APIs!

  Seriously though, Sun needs to take these APIs into the street before releasing them publicly. Seven classes and interfaces to represent one table in EJB? Come on. That's just silly.

  Posted by: jherr on February 17, 2004 at 08:52 PM

• String aPainfulRead = "The Design of Everyday Thigngs";
  I am an Information Technology student at the Rochester Institute of Technology. In a Human Factors class we were forced to read that book "The Design of Everyday Things." All I can say is that it is perhaps one of the most boring books to read that has ever been written. The author seriously whines about everything.... In fact some of the examples he uses, are even logical in design. If you find this book fascinating, run, you have way too much time on your hands...

  However, lots of APIs are poorly designed. Look no further than the Java3D API. To get any realy 3D stuff going you have to create a whopping number of objects thus making the framework totally impractical for real use. Oh yea, it is really slow too ;).

  Posted by: java49 on February 19, 2004 at 10:54 PM

• String aPainfulRead = "The Design of Everyday Thigngs";
  Well, I have to agree that he seriously whines : ). I did find *most* of the book fascinating though, and I was in a Knowledge Design Study Group (kind of an Oprah's Book Club for Information/Interface/Knowledge design) and the whole group loved it. But I dearly *wish* I could say that I have time on my hands. I just love this stuff, and I like the way he talks about it, because almost anyone can appreciate the concepts, without having to be a professional interface designer or human factors student. Anyone who ever had trouble programming the first generation of VCRs can appreciate at least *some* of his whining. ; )
  But since you complained about it... I'm going to ask you what you WOULD recommend, as a foundation book. Because now that you mention it, the book is *not* the perfect book, but I'm having trouble coming up with one that I think would serve the same purpose better. If I could, I'd probably pull 30% of Norman's book and combine that with something from Richard Saul Wurman's Information Anxiety, and maybe *some* bits and pieces from a few interface design books (Don't Make Me Think, the Humane Interface), a book on the brain, something from Roger Schank, and... I don't know.

  I don't think it's good to focus just on computer interface design, though. And I know that you found Don's book boring, but *why* did they force you to read it? And where do folks get that initial foundation in understanding the importance of (and approaches to) design? I think that one of the best parts about that book is that he offers guidelines and recommendations that can apply to the design of *anything*, even if you don't agree with all of them. Most books are too tightly focused on one particular aspect of design, rather than the deeper principles, which I believe he summarizes better than other books.
  Not everyone finds that book boring, though. It *was* a bestseller, and it was even made into a pretty fun interactive CD-ROM (where he was physically *in* the interface, standing there pointing up at menus and buttons and talking about them). Then again, most of those might have been people like you who were *forced* to read it ; )
  
  Anyway, I'd love to hear your recommendations... it sounds like you're right in the thick of things at RIT, and you might have seen something else that you really DO like, and if it's more exciting but covers the same general fundamentals, I'll start recommending it instead. (And yes, I agree with others about the importance of Tufte, but I haven't found any of his books to be a "general foundations of design" starter book.) So the question is, if you could tell everyone to read only ONE book that would help them appreciate and *implement* better designs for interfaces, APIs, and anything else... that's it, just ONE, what would it be?

  cheers and thanks, Kathy

  (Who once moved into a new apartment and called the landlord at 7 Am the next morning because I couldn't figure out how to make the water come out of the SHOWER head instead of the bathtub faucet.)

  Posted by: kathysierra on February 21, 2004 at 04:58 PM

• Ivory Tower Syndrome
  "Either Arrays.sort() or Collections.sort() method can be used to implement self-sorting JTable."

  Fair enough for the specific example -- I originally started using JTables in 1.1.x, where you couldn't access .sort(). Swing preceeded sort(), and there's your Ivory Tower in this case.

  But even if you're not targetting 1.1.x any more, what if you'd like your model to reference a database's contents directly through JDBC?

  The point is that, with Swing and other Ivory Tower APIs, you have write non-trivial code and understand non-trivial concepts to perform mundane tasks. The APIs have all the power they could ever want *in theory*, but in practice APIs born of Ivory Tower Syndrome have some real drawbacks. As the OP said, "pity those of us who have to LEARN this".

  Posted by: rufwork on February 25, 2004 at 07:25 AM

• wow power leveling
  wow powerleveling
  wow power leveling
  wow gold
  wow items
  feelingame.com
  wow tips
  Most Valuable WOW Power Leveling Service
  wow power leveling faq
  cheap wow power leveling
  wow power leveling
  wow powerleveling
  wow power lvl

  Posted by: wowleveling11 on December 14, 2007 at 06:05 PM

• 网络营销软件
  网络营销软件
  网络营销软件
  群发软件
  群发软件
  ---
  群发软件
  网络营销软件
  论坛群发软件
  网站排名软件
  群发软件
  推广小助手破解版
  论坛群发软件
  网站排名软件
  群发软件
  推荐给你很好的群发软件和信息群发软件和供求群发软件
  推荐给你很好的群发软件和信息群发软件和供求群发软件博客群发软件网络营销软件网络营销软件
  网站排名软件网站排名软件网站优化软件信息群发软件信息群发软件信息群发软件论坛群发软件网站推广软件网站推广软件博客群发软件博客群发软件
  群发软件
  网络营销软件
  网站推广软件
  群发软件群发软件博客群发软件论坛群发软件网络营销软件论坛群发软件
  信息群发软件推广软件网站推广软件网络营销软件网站推广软件群发软件网站排名软件网站推广软件博客群发软件论坛群发软件群发软件网站排名软件网站推广软件博客群发软件论坛群发软件
  网站排名软件
  博客群发软件
  网站排名软件
  网站推广软件
  群发软件信息群发软件
  免费论坛群发软件
  论坛群发软件
  网站排名软件
  免费博客群发软件
  网站推广软件

  群发软件
  博客群发软件
  网站排名软件
  网站推广软件
  群发软件信息群发软件
  免费论坛群发软件
  论坛群发软件
  网站排名软件
  免费博客群发软件
  博客群发软件
  信息群发软件
  论坛群发软件
  信息群发软件
  博客群发软件
  qq群发软件
  邮件群发软件
  博客群建软件
  企业名录搜索软件
  信息群发软件
  邮件群发软件
  论坛群发软件
  博客群发软件
  网站推广软件
  网络营销软件
  全能营销破解版
  网络营销软件
  论坛群发软件
  论坛群发软件
  论坛群发软件
  网络营销软件
  信息群发软件
  信息群发软件
  信息群发软件
  群发软件
  论坛群发软件
  

  Posted by: sun98989 on December 30, 2007 at 05:56 AM

This work is licensed under a Creative Commons License.