Experts and non experts
I had an interesting conversation with a colleague of mine last week. We were discussing
the extent to which full details of a technology or feature should be exposed to end-users.
We were discussing this issue in the context of the IDE specifically, and how details
should be exposed in the UI, but the issue is also relevant when considering APIs.
For example, consider the System.Xml namespace. This namespace exposes a set of types
that provide standards-based support for processing XML. For example, the XmlDocument
class implements the W3C Document Object Model (DOM) Level 1 Core and the Core DOM
Level 2.
XmlDocument exposes members such as CreateDocumentFragment, CreateElement and CreateNode.
If you're familiar with the details of the W3C DOM you'll know which method to choose
when you want to add a new data record to an Xml document that you're using as a database.
But if you're not as familiar with the W3C DOM, you may not know which method to use
to accomplish your task. You'd need to become familiar with the DOM before fully understanding
what the different methods do and when you should use which one. Likewise, if you
wanted to run a query over your data, you'd need to know about XPath and that you
create an XPath expression to select the nodes in your document that meet the search
criteria.
This is all fine if you are comfortable and familiar with all things XML. But if you're
not, it may be somewhat daunting - there is a lot to learn. The rewards are potentially
pretty large, but the tax you have to pay to reap those rewards may also be pretty
large.
The question is, does the developer always have to be forced to pay this much
tax or is there a way that the API can be designed such that the developer who does
not have as much familiarity with all things Xml can still reap the benefits?
It's basically a trade-off between making experts comfortable and providing them with
an API that maps very well on to their expert view of the domain at the expense of
requiring non domain experts to become domain experts or to forever remain uncomfortable
using the API. Or, making non-domain experts comfortable with an API by abstracting
over some of the domain specific aspects of the API but by so doing making experts
less comfortable since everything that they know about the domain will not be represented
in the API as they expect it to be.
My colleague and I concluded that it really comes down to the percentage of domain
experts and non-domain experts in the user population. We figured that if 10% of users
were experts and 90% were non experts, it would be unreasonable to force the non-experts
to become experts before they could use the API effectively. But we did not come up
with a point at which we felt it would be reasonable to make users learn a bit more
before they could use an API. Is it 50/50, or higher or lower? One argument suggests
that over time people will become experts in the domain the more that they use the
API. But another argument suggests that if the cost of being able to use an API is
too high, people won't even bother with it, or may use the API incorrectly, leading
to inefficient code etc.
Given these arguments, at what point do you think it is reasonable to have to invest
significant time to learn about the domain that an API abstracts over? We'd love to
hear your opinion on this.
Comments
- Anonymous
November 03, 2003
While I think that the System.XML namespace is a good example... a better one would System.Security. I know for my self that diving into this is needed, however, the tax, as you so aply put it, is making it very hard to get into. This is a space where access to the API is fundemental to success, but the knowledge that appears to be needed to use it correctly is far beyond the casual user. To date - I have to admit - it is beyond me. So how to handle this kind of issue?I personally think that it comes down to this. How vital is the API? Is it something that being a domain expert is a good thing to be and/or not to bad to learn - then the decision is not too hard. Code for the experts - and those that want to use it will come. But for something that is a day in, day out subject matter, and a very hard matter to work with - write the API to the lowest possible level of knowledge. The experts will dig a little deeper, but more programmers will at least use the API.David - Anonymous
November 03, 2003
Having invested a fortune in college degrees, certifications, and my own hard knocks, I believe that providing API's to the general masses is a mistake. Programming should be left to those who understand what they are doing.An example was the boom in web programmers when any one with Word thought they could create web pages. I've spent the last several years cleaning up after programmers who thought they knew what they were doing with ASP but could not get their web application to scale.I think the .NET documentation could be better in several areas with better "real world based" examples. But please don't "dumb down" the API. If you're going to use the functionality provided by the API, the programmer should understand how to use the API. - Anonymous
November 03, 2003
Do both. Design the expert UI first, as presumably your API designers are top-flight domain experts, and then design a 'helper' API and implement it in terms of the expert API. Ensure that non-domain experts are involved early and often in the design of that second API. (Should that be domain non-experts? :-)Put the helper API in a consistently named child namespace of the expert API, so System.Xml and System.Xml.Helper, and be disciplined about ensuring the helper API is implemented exclusively in terms of the expert API. For bonus points, ship the source for the helper APIs as a way to assist those non-experts in becoming experts if they wish.(Note: 'Helper' is probably a lousy name, but the idea remains sound.) - Anonymous
November 03, 2003
I absolutely concur with Blake (and was just about to write something similar, until I saw he had got there first).As is often said in the Perl community: "There's more than one way to do things". - Anonymous
November 04, 2003
The comment has been removed - Anonymous
November 04, 2003
The comment has been removed - Anonymous
November 04, 2003
The comment has been removed - Anonymous
November 04, 2003
Well as most of the others say both is the best option. But one thing to keep in mind is that the object model should be the expert one, but the helper API makes it easier to access/work with the expert object model. So over time if the user understads the system well enough to be an expert, he can move over easily by just changing the API set. - Anonymous
November 16, 2003
It could be that Blake is talking about what Microsoft is trying to accomplish with Application Blocks. They are even publishing the source code to ABs so the get the bonus points! I absolutely think AB are the right way to address that 80% of cases when coarse grained code will cut it, also that 80% of programmers that are not experts, and even that 80% of the times when expert programmers have better things to do with their resources.So my wish in this regard is well designed and well documented APIs, and more and better Application Blocks.