A fellow developer on OpenNLP, Jörn, recently pointed me to a blog post where Daniel McLaren provides a nice turorial to OpenNLP. I went looking for more posts like this and found a crabby blog post about a lack of documentation on OpenNLP from someone who who didn't find the README file and spent their time kavetching about it. Admittedlly it was harder to find when they wrote their post, but there are plenty of forum post pointing to it. While our documentation could definitely use improvement (and is being improved) the craby post misses the point on a number of levels.
The first point miseed is that our medocre documentation might be intentional. Historically, the documentation for OpenNLP has been intentionally selective. This software is targeted at developers. Parsing or the other things OpenNLP does are not applications in and of themselves so the only users are developers. Command-line tools are provide with examples of how to run them and they generate usage information. After that I expect that anyone using the software:
- Know how to compile it
- Know how to set their classpath
- Know that the command line tools must have a main() in them.
- Can read that main() and javadoc to figure out how to use them
The main()s are pretty straight forward as Daniel McLaren's code shows. Previously, I've considered providing more documentation, but I've been worried that it will just invite more forum questions from people I can't really help and I spend a good deal of time answering those now.
I could justify a number of other points in response to the crabby post like why the models aren't included in the source package, licensing differences with the other parsers he mentions, what it means to be a successful open source project, yada, yada, but here is the real point I want to make.
The crabby post makes a good point when it say: "Maybe Daniel and Thomas Morton (author of OpenNLP) should talk.". My question to the author and the other complainers out there is:
- What did you do about that?
- Did your actions make any difference in addressing your underlying concerns?
- Can you say that you caused that difference to be made?
The guy who told me about Daniel's page, Jorn, is a contributor. Seeing Daniel's post has me looking at incorporating some of what Daniel did in upcoming documentation as I now see that it provides something, without inviting a lot of ill-formed questions. I found the crabby post looking for other content like Daniel's.
The crabby blogger also has a post on using BufferedInputStream to optimize model loading, but that's where it ended. Marc Schröder made the same observation, but actually put it in a bug post. That made a difference and will be an upcoming incremental release.
Do people get that they are using free software contributed in people's free time and just how stingy it is to complain without taking the next obvious actions to make a difference? If there wasn't such a huge untapped potential for others to contribute and make a difference in wherever they choose to I wouldn't even bother writing this.
Consider being a contributor in life! It's probaly no more effort than what you put into complaining and it makes the world a better place.
