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.