I think code examples are something that are best included in the "getting started" section of documentation. It gives the user a quick, usable, concise illustration of how to perform the most basic tasks. Sometimes that's all you need and this is frequently omitted by some software documentation.
Test cases are certainly useful if you need to dive into comprehensive/advanced usage of the API. But if you just want to "get started", a huge vat of unit tests can be daunting.
Technically, all the code in your program could rightly be called a "code example." But it's not very good for determining how to use the code in your program. Test cases are closer to being good code examples, but they're still generally optimized for checking correctness rather than illustrating use. If nothing else, a good, complete set of test cases will be full of distracting noise.
Definitely agree- usually whenever I start looking at the source of an open source project it's difficult to figure out where things are. A top-down view of the project's architecture, besides just the source tree, would be extremely useful in situations like that.
I agree that understanding an Open Source project without proper documentation is really hard. For the same reason we are trying to create this site (http://www.codemaps.org/s/Lucene_Core) to document open source projects. This is still in beta and we would be glad to hear your thoughts on it.
So, developers need and want Overview Documentation, and Overview Documentation is not the same thing as Reference Documentation (which is what tools like JavaDoc produce.)
Does anyone find this surprising?
Regarding code examples vs test cases: they're different in the same way Overview docs are different from Reference docs. The code examples are part of the overview, and show the typical / most common ways of using the code. The test cases are like reference docs, and show every nuance and feature of the code, including all variations on argument and response types and error paths.
I once remember taking over maintenance of a previous project and being handed 20-25 pages of minute details(mostly meaningless to anyone but a newbie to the s/w). But no mention of what happens overall. I spent a day to come up with a workflow diagram (in a page) that made quick sense.
P.S: for those who like to blame outsourcing to India, this one was from a U.S contractor
I have been very frustrated in the past when the only documentation provided was javadoc. In many cases there was an xml that was not documented very well, and subtle things about the classpath that kept the system from working. Often the javadoc is just regurgitating the name of the method. In many cases the javadoc reminds me of the help systems in windows programs. I think I remember seeing a discussion on reddit where they were asking if anyone had ever found an answer in a windows help topic.
I agree, no one type of documentation can live in a vacuum. Ideally, javadoc, sample code, tutorials, diagrams, and summaries/explanations would be present for every code base. But in reality I find even a few simple diagrams combined with a insightful description is infinitely better than pages of minimal javadoc.
11 comments
[ 538 ms ] story [ 5791 ms ] threadTest cases are certainly useful if you need to dive into comprehensive/advanced usage of the API. But if you just want to "get started", a huge vat of unit tests can be daunting.
I agree that understanding an Open Source project without proper documentation is really hard. For the same reason we are trying to create this site (http://www.codemaps.org/s/Lucene_Core) to document open source projects. This is still in beta and we would be glad to hear your thoughts on it.
Does anyone find this surprising?
Regarding code examples vs test cases: they're different in the same way Overview docs are different from Reference docs. The code examples are part of the overview, and show the typical / most common ways of using the code. The test cases are like reference docs, and show every nuance and feature of the code, including all variations on argument and response types and error paths.
P.S: for those who like to blame outsourcing to India, this one was from a U.S contractor