I have been wrestling with ht://dig for the last few days. Couldn’t get it working. That’s another story. But I thought it might be good to try Lucene, since I heard that it was a search engine, and it’s an Apache project. So, I went off to the Lucene web site, and tried to figure out what would be involved in installing it. Is it a thingy that I can put directly on my Apache web server? Do I need Tomcat, or one of those inscrutable Jakarta thingies? Is it stand-alone in some sense?

Tha “getting started guide” says that you have to have Tomcat or some other “container”, whatever a container is. It also talks about such things as Template Web Applications, and has the following delightful sentence:

One would hopefully use MVC architecture such as provided by Jakarta Struts and taglibs, or better yet XML with stylesheets.

Now, I’m perfectly confident that that makes perfect sense to a significant number of people, but I’m finding this to be utterly inscrutable. It looks like I’m going to have to go get Tomcat running, and possibly learn about MVC, Struts, and taglibs, whatever those are, before I can even start to install Lucene. And forget using it as an example in my Apache class.

So, then I went over to the wiki. A number of Apache projects have moved to Wikis for their documentation, because, we are repeatedly told, it is better in every way, allows people to edit the documentation easily, and contribute without barriers, and so, obviously, will produce better documentation.

I searched for “Installation” in the wiki. Apart from the irony of a web site about a search engine using a different search engine for indexing, I found the results intrigueing. All the pages that were returned by this search were about installing something called MoinMoin, which is apparently the Wiki software itself. None of the search results had anything to do with Lucene. I don’t know if this means that the documentation is terrible, or that the search feature of the Wiki is terrible, but neither one of thse was particularly comforting.

A couple months ago, someone on a mailing list I’m on criticized Apache (The ASF in general) for the terrible documentation that is the hallmark of our software. I took great offense, and went to some length to defend the Apache Web Server documentation, which is, in my opinion, among the best of any free software product, and better than most commercial products.

I might be compelled to retract my statements. The Apache Web Server does indeed have great documentation, but each time I look at some of the other products, I’m apalled by how little information is conveyed by the docs. Many of the projects, it’s almost impossible to even find out what the product does, let alone how to install or use it. The documentation, when there is any, is directed to the developers, not to the users. The developers don’t need to be told basic things like what the product does, where to get the dozens of prerequisites, and what all the jargon means. But I don’t really think that documentation *should* be directed at the developers. The folks that want to use the product are utterly in the dark, and, as often as not, throw their hands up in disgust and go look for something else. Something a product that’s not as good, but which is easier to figure out.

People don’t like feeling stupid. Documentation that makes people feel stupid leads to people choosing a different product. Documentation that uses words like “simple”, “basic”, “easy” and so forth makes people feel stupid when it’s not easy for them. Documentation that assumes vast bodies of existing knowledge without even a nod towards somewhere to go to learn more about it, or even suggesting that you might need some existing knowledge, makes people feel even more stupid.

I’m reminded of the Geronimo demo at ApacheCon, where there wasn’t even a mention of what they were demonstrating – we were all supposed to know. This made me feel uninformed, and, yes, stupid. This is how the Lucene docs make me feel. There’s an underling feeling that I’m missing most of what is being said because of a great gap in my knowledge, but there’s no suggestion as to where I can go to fill that gap.

For the record, Zope makes me feel the same way.