NHibernate is OSS. You can download the source code for free, make your own changes, recompile it, push that source code back to the VCS, etc etc. Does Ayende require you to dig through the code, and that of Castle's DynamicProxy, in order to effectively use his library to implement your persistence layer? Of course not. The NHibernate community provides a pretty good set of documentation and best practices for using the NHibernate library. Similarly, the Fluent NH add-on has decent documentation; you don't have to dig through the library's code to figure out what it does and how to use it.
In short, even OSS should conform to the "black box principle" from the perspective of the end user.
Coders expect their libraries to be packaged much like their electronic equipment: they expect to receive an instruction manual along with this "black box", that tells them how to hook it up and how to communicate with it. If they don't receive a manual, the smarter among them will look at what does come in the package, will expect to see very clear labels for where things plug in to it, and will assume no specialized knowledge is required for operation once it is set up properly. If neither of these is true, the coder will likely be calling the library's developers for help, much like you'd be calling tech support if you didn't have all the info you needed to set up your TiVo. The last thing you would do is crack the seal on a brand-new, warrantied piece of equipment and try to trace through it yourself, much like the last thing the coder would do is pull up and trace through the library's source code for a clue as to its inner workings.
Similarly, OSS projects that aren't effectively documented in some other way than code fall into one of three categories:
- infant projects - the documentation is simply not yet well-developed because the focus is on proof-of-concept and thus working code. Users of the code at this stage are "beta" testers, and understand its "as-is" nature on all fronts including documentation.
- extremely simple - the stated purpose of the library, the names and signatures of the classes and class members as viewed from some object browser or by JavaDocing the JAR, plus maybe a simple demo, tell the user all they need to know.
- dead or dying - nobody wants to take the time to figure out how to use the library by trial and error, or by inspection, so nobody's using it.