My recent remarks about documentation, and, in particular, picking on Lucene, generated a range of comments, most of which were more insightful than the original article, as is usually the case. In particular, I’d like to thank Leo for his remarks, as they’ve made me think, which is usually a good thing.

What I’d really like to see is a page for each ASF project which says what it is. And, perhaps just as importantly, says what it is not, based on common misunderstandings. This page could further discuss, as Leo suggests, who the “target market” is for the product. And, finally, it should reference the prerequisite reading material, prerequisite technologies, and prerequisite knowledge, which would assist someone that wanted to understand and/or use the product.

Of course, it behooves me to do this for HTTPd before I suggest that other projects do the same, but if some projects want to go ahead and do this, it would be nice if we could agree on a convention for URLs of this document. Something like http://$PROJECT.apache.org/about.html, for example, so that folks know where to look. Those folks that Trust In Wiki might, possibly, be compelled/encouraged/persuaded to provide such a URL, even if it was just a redirect to the relevant Wiki page?

And thanks to Leo for pointing out that I, too, am guilty of the “well, everybody knows what that is” line of reasoning. Because, of course, everyone knows what a web server is, right? And exactly what I was complaining about earlier was the “everybody knows what J2EE compatibility is” attitude that leaves those who *don’t* know feeling that they have missed a memo somewhere.

And, lest people think I’m picking on only Lucene, allow me to point you at a number of other examples.

Here’s my favorite so far. Gump is a social experiment. Yep. That’s what it says. I gather, from further reading, that Gump might be some kind of project management thingy, but I’m not yet certain. And if it is, then I’m not sure how it’s different from Maven, how it’s similar, and how, if at all, they interact. There is a very interesting page about why Gump was written, but I lack the prerequisites to understand most of it.

So, we’re all guilty of this to some degree, and I include HTTPd in that, thanks to Leo’s remarks. Something to think about in my Copious Free Time.

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.