There is always a tension between giving users an interface that is simple to use and giving them something that is powerful.
With RavenDB, we run into a problem with the session interface. I mean, just take a look…
Look how many operations you can do here! Yes, it is powerful, but it is also very complex to talk about & explain. For that matter, look at the interface:
We have 4(!) different ways of querying (actually, we have more, but that is beside the point).
Something had to be done, but we didn’t want to lose any power. So we decided on the following method:
Basically, we grouped all the common methods into a super simple session interface. This means that when you need to use the session, you see only:
4 of those methods (Equals, GetHashCode, GetType, ToString) are from System.Object and one is from IDisposable. Users pretty much are going to not see those methods. The CRUD interface is there, as well as the starting point for querying. And that is it.
I think that it makes it very easy to get started with RavenDB. And all those operations that are important but uncommonly used are still there, they just require an explicit step to access them.