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.