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
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
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
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.