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.
+1
I really like the idea of a page that just explains what things are, what they are not, the required reading, etc. I know when I first started investigating Jakarta it took me a while to figure out what all was there and I kept worrying that perhaps there was some perfect project just waiting to solve my problems but because I wasn't familiar with everything it would go unnoticed.
So I would recommend not only each project doing this on its "about.html" page or whatever, but having a good summary page for all of Apache. Perhaps a "tour of the ASF".
Documentation in Avalon has been my personal crusade for a little while and it is a daunting task. Avalon has horrible documentation. It's getting better, but it's not what it should be. And I actually like writing documentation. As far as I am concerned, it's what really makes a project stand out and prove that it's polished.
Posted by: jaaron on May 7, 2004 10:32 AMI think the http://xml.apache.org/ page does a very good job of giving a tour of the XML projects. I know forrest, though, certainly could use some improvements in documenting the features, non-features, and news/history.
Posted by: Dave Brondsema on May 7, 2004 01:21 PM