This came in the mail yesterday.

Just a quick note to let people know that I’m still alive. I’m at Big Nerd Ranch, in the wilds of Georgia. We’re out of cell phone range, with sporadic Internet access, beautiful scenery, wonderful food, and really good students. I’ll have to write more about it later. The facilities are fantastic. I was a little nervous about teaching Apache in the middle of nowhere, but it’s awesome.

More later.

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.

I forgot to mention one thing about my trip up. I had lunch at Joe Huber’s Family Restaurant, a mile or so down the road from the Huber Winery. It was pretty incredible. I had some kind of fried fish. I’m not entirely sure what I had. I asked them to just bring me something good, and they did. I was wondering, while I ate, whether *all* the girls in that part of the country are that pretty, or if, somehow, they just got the prettiest ones to work there.

Anyways, class started yesterday, and, of the 5 people signed up for the class, 3 showed up. Once again, I have really good students, which always makes the class go better. However, Solaris had it in for me yesterday, and we spent the *entire* morning just getting Apache + SSL + mod_perl + PHP installed. Then, being flustered about the morning, I picked up the pace in the afternoon, and, of course, finished very early. Bah.

I had big plans for the evening, mostly involving GeoCaching, but I was exhausted, and sat like a lump and watched “Battle of Britain” on my laptop. I snagged it the other day because I remembered watching it at Turi, lo these many years ago. The scenes that I remembered most vividly were exactly as I remembered them.

It’s time to go get some breakfast, and then start day two.

This came in the mail today.

I spend an inordinate amount of time on IRC. In particular, I spend hours every day providing Apache tech support on #apache on irc.freenode.net. I’ve often wondered if there’s a way to bill for some of this time. 😉

Well, today in the mail I received a Gerber multi-tool, which I had put on my Amazon.com wish list. There was a short note saying thanks from all the folks I’d helped on #apache. The individual who sent it, who I won’t mention by name, as I did not ask his permission to do so, is a true gentleman. I certainly don’t expect anyone to compensate me for my contributions – it’s part of what I give to the Apache documentation project – but it is enormously gratifying to be appreciated. 🙂

On a related note, I ran some simple stats on the #apache log files, and apparently I say 3.4 times as much as the next most prolific person, and more than the next 5 people combined. And one of those 5 is a ‘bot, so hardly counts. Obviously I spend *too much* time on IRC.

I’m just a little disgruntled. I’m not sure if I was quoted out of context in an attempt to make it appear I was saying something I wasn’t, or if I’m making too much of it, or if my remark was really so imprecise that he didn’t know what point I was trying to make.

I felt that the question was intended to make me say that the security fix was applied only to 2.0 because 1.3 is intrinsically more secure. That’s not really the case. If anything, I think that 2.0 is probably more secure, simply because it is more thoroughly designed. But on both versions, security holes are fixed as soon as they are found. So if we thought that one was more secure than the other, that would be immediately rectified.

I dunno. I’m probably making too much of it.
.

When the @author tags issue came up, I refrained from comment, because it seemed to be an issue only with the Java folks. And it’s clear to me that I don’t understand the Java folks, on a number of levels. They seem to be motivated by entirely other things than I am, and so we seem to have a number of disconnects on things that they appear to consider very important.

The things you think are precious I can’t understand
(Steely Dan, Reeling in the years)

So, for those joining late, the ASF board has suggested that @author tags in Java code should be avoided. Not, you should understand, saying that they MUST be removed NOW NOW NOW, but that they are deprecated — not recommended.

This upset a lot of people.

You should read Ken’s remarks on it (here and then more here) for a more in-depth analysis. After all, he is on the board, and I am not.

To me, however, this all begs the question, why are these folks involved in Open Source? I do not mean to imply that this is a simple question, or even one to which everyone knows their own answer. I have thought a great deal about my answer, and I still don’t know that I have one simple answer. Certainly, part of it is for the adulation and glory that comes along with it. And part of it is just the joy of doing something that really matters – something that has significance beyond myself. I’d like to think that the latter has more weight than the former, but the scale slides from one day to another.

But should we have author tags in files? There are docs in the Apache HTTPd documentation that state “this doc written by”, and those have always irritated me. Having thought a lot about it, here’s the reasons that it irritates me.

1) Code ownership is BAD. This is one of the tenants of the eXtreme Programming folks. Yes, this is dogma, not a reason, but I tend to agree with the XP folks more than half the time, so there’s likely good reasons behind it, in addition to my reasons.

2) Why is code ownership bad? One reason is: Because people get their feelings hurt when “their code” gets changed. They take it as a personal affront.

3) Another reason: People are reluctant to touch it. Why has the mod_rewrite documentation remained unchanged for so many years? Because it is Ralph’s document. Has Ralph stated that he doesn’t want it changed? *Of course not*. But people seem to be reluctant to change that one doc, when they tromp all over other docs. I suspect that the same is true to some extent for “my” howto docs, which is why I went back and purged my personal information from them.

4) And another: It reduces the community’s pride in a document. When everyone has contributed to a document, they all feel that the’ve done a good job. Same with code. But if people are keeping score – I wrote 28 lines, and you only wrote 12 – that gets to be more of a self-aggrandizing contest than anything actually productive. The person with the most lines of code is seldom the most important contributor. Often the one-line patch is worth more than 100 lines of broken code.

I didn’t feel that it was worthwhile piping in to the @authors argument, I suppose, because it was clear to me that the board decision was the right one, in the overall goal of improving community. And that it was not dictatorial, so that if an individual project wanted to say, no, we want to keep them, well, then, they can. Also, because the Java people baffle me on the best of days, I was sure that I’d unintentionally step on toes and call someone a self-aggrandizing pompous stuck up fame-seeking gold digger, or something like that. 😉