It's understandable that after a big development effort, some OSS authors deem reasonable that the project users should make an effort too in order to get started.Can the source code effectively be the project's documentation? Does it need to be structured in a particular way in order to achieve this? And how often is this approach taken?Of course this only would be feasible if the project is aimed to developers, and written in the same targeted language of the application (e.g. you can't understand the V8 engine only knowing JavaScript).
Can code be the documentation in open source developer tools? How frequently is it?
open source;documentation
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.