Tag Archives: tech

What’s the documentation for?

There are, it seems to me, two purposes to which documentation is put.

Most people consulting the documentation are attempting to fix something that’s broken, or otherwise get something to work. This is the “tell me how to do it” variety.

A smaller number of people consult documentation in order to gain a deeper understanding of how things work, and why. The motivation for this is varied, of course, but it’s a different goal than simply getting something working.

The former way of looking at docs is very short term, immediate, crisis. The latter is more long-term. Generally, if one reads the docs and understands how things work, and why, they tend to have fewer of the crisis situations in which they need to get something working.

There’s a documentation bug about the Order directive which is grounded in this very difference. The Order syntax is annoying and unintuitive, if you don’t understand how it works, and why. Most people don’t want, or need, to understand why. And, in this case, the “why” is not particularly simple. Folks just want to know how to get their allow and deny directives working. And the docs currently don’t really help them do that. At least, not right now. Hopefully they will in a few days.

My goal in documentation is generally to first address the “how do I fix it” question, because that’s the most frequent use of the docs. I don’t necessarily think that folks *should* have to understand the inner workings of the configuration directory-scope merging mechanism in order to keep the nasty spammer out of their content.

However, most of the technical documentation that I encounter is of the “how does it work” variety, and a great deal of it doesn’t even do a good job of that.

I’m just rambling, and observing. I don’t know what the solution is. There’s certainly a lot of “howto”‘s out there, and so many of them are either very specific to a particular scenario, or just plain wrong. These are a well-meaning approach to the problem, but often go astray.

Whitelisting

Thanks to an article by Skippy, and considerable time staring at Postfix, The Definitive Guide, I’ve gotten a whitelisting system set up for my daughter. She can now receive email from a very select list of addresses. Anyone else gets rejected.

The second part is to get a whitelisting proxy server set up for her.

The goal is to give her her own computer for her birthday, but to make it completely internet-proofed. I want her to be able to go to her favorite websites, but not to other places.

And, no, I’m not interested in your remarks about how overprotective I am, or how I’m stunting her ability to learn, so don’t even bother.

I briefly considered using Squid, but I think I’ll try to do it with mod_proxy first. Probably not ideal, but I figure you should eat your own dogfood whenever possible.

Change your password, folks

I got a new wireless router/firewall thingy this morning. Various reasons. Long story.

Anyways, got it home, plugged it in. Restarted wireless networking on my laptop, and got onto the admin pages. Logged in, and started changing all the configuration options to what I wanted. Once I had it all configured, I started testing the port forwarding settings, and realized that nothing was working the way that I thought it was.

After trying various things, I decided to do a factory reset, and start again. I unplugged it, and noticed that my wireless signal strength didn’t drop at all. Turns out I had been configuring some neighbor’s gateway.

So, the moral of this story, folks, is that you need to change your SSID and your password when you get a wireless gateway. Yeah, I know, they are supposed to just plug in, turn on, and Just Work, but, come on.

IRC sabatical

The goal was to stay off of IRC for my entire vacation, but this morning I saw that Fajita had been flatlined since about 2pm yesterday, but that the process was still running. So I popped in to restart her.

1103895276 [119] &ltFajitaKeeper/#apache&gt fajita: seen DrBacchus

1103895276 [118] <fajita/#apache> DrBacchus was last seen on #apache 7 days, 17 hours, 4 minutes and 12 seconds ago, saying: Well, I’m taking a break from #apache until December 27th. Y’all have a wonderful Christmas, and don’t forget to look in the error log. [Thu Dec 16 15:30:24 2004]

And 7 days, 17 hours, is pretty impressive. I don’t know that I’ve been off of IRC for that long at a stretch, since I started IRC’ing. That’s kinda sad.

New keyboard, new laptop

The first shipment of my “new laptop” arrived today. I have a new keyboard. And the difference is so great that it’s almost like having a new laptop. Although I’m sure that having a new laptop would have been more satisfying to my technology addiction, this is pretty good. I’m almost completely convinced that I made the right decision.

Why just almost? Well, one of the side effects of my AC adapter going out is that it toasted my battery. The battery thinks that it is 100% charged, but it can’t actually keep the computer running for more than about 2.5 seconds. Apparently this is one of those batteries that has a very good memory of what its empty point is, and, apparently, it thinks that it is 98%. So I need a new battery, too. Unless I can find a way to totally discharge this one, and reset its bottom point.

So, off to Google go I.

Wireless … and useless

I’ve been hanging out at Coffee Times for the last few mornings. Sarah is in a craft day camp, and they chased me off because they’re making something for me. In the past, the wireless network here has been wonderful, but today and yesterday, it’s been very painful. 15% signal strength, and it just goes away every 5 or 6 minutes, for about 2 or 3 minutes, then comes back. The folks here don’t know anything about it. A local ISP set it up and left it. So there’s nothing that they can do about it here. Very very annoying. I suppose I should just enjoy my coffee and read something. But I had hoped to get some programming done. Ah, well.

PHP’s anti-Apache2 FUD

My biggest objection to PHP is the anti-Apache2 FUD that they spread. Indeed, they seem to be the ones primarily responsible for the anti-Apache2 FUD. This is unfortunate, since there are few remaining legitimate reasons for avoiding Apache2, and it’s a shame that they feel the need to manufacture one.

So, to quote the PHP docs:

Do not use Apache 2.0.x and PHP in a production environment neither on Unix nor on Windows.

This is further clarified in the FAQ with a long description which starts, unfortunately, with a misconception, namely:

The major feature that draws people to Apache 2 is threading.

It then goes on to explain why threading is, potentially, a problem with PHP, why this is not, technically, PHP’s fault, and so PHP cant fix it. All very correct, really. And, so, very logically, it concludes that there’s no reason to move to Apache 2, and that everyone should stick with Apache 1.3.

This argument suffers from one main flaw. That is, that the initial assumption, from which everything flows, is just plain wrong.

Yes, threading is cool, and is a major shinyness with Apache 2. However, it is not, by any stretch of the imagination, the only, or even the main, reason for moving to Apache 2.0. There are a *lot* of other much better reasons for moving to Apache 2.0, none of which pose any threat to PHP. I’ve covered those in my OnLamp article, and so won’t repeat them here. Apache 2.0, running with a prefork MPM, works great with PHP, and gives you all those other benefits.

The additional benefit is a little more subtle. Apache 1.3 is becoming “legacy”. Meaning that the real developers are focusing more on 2.0. The 2.0 docs are better. 2.0 (and 2.1) gets the new features, the documentation improvements, and the newly clarified directives and error messages. Thus, 1.3 becomes harder and harder to support. So, increasingly, the PHP questions are coming from folks that are running 1.3, and the solutions offered just don’t work, because they are things added in 2.0 to solve exactly the irritations that these folks are having.

So, I entreat the PHP folks to remove this incorrect anti-Apache 2.0 tirade from their documentation, and replace it with a more balanced and correct explanation of the issues involved, and the recommended solution. Namely, that people go ahead and move to Apache 2.0, but stick with a Prefork MPM. This gives them most of the benefits of Apache 2.0, but removes the irritating threading issues. Nobody blames PHP for those threading issues (at least, people who have taken the trouble to actually understand the issue don’t), so there’s no slight on the PHP developers implied here. I’d be glad to participate in this to any degree that you like. I actually enjoy writing documentation, and I’m increasingly using PHP for my own work.

Please?

Why we don’t like PHP

I’ve started using PHP lately, and I find that I quite like it, as a language. However, there’s a lot of anti-PHP sentiment on #apache (on freenode.net), and folks often wonder what the source of that is. Well, there’s several main reasons, some of which are:

  1. The anti-Apache2 FUD spread by the PHP folks
  2. The #php redirect effect
  3. The “scripture with commentary” nature of the documentation
  4. The misuse of AddType vs AddHandler

The first one of these, the anti-Apache2 FUD issue, is one that’s important enough that I’ll probably write as a seperate article.

The next one, the “#php redirect effect,” is pretty irritating. On #apache, we attempt to be very helpful, and so we end up answering questions on a variety of topics which are, strictly speaking, off-topic. Invariably, however, when we refer someone to #php for questions which seem to be likely to be more in the experience of folks familiar with PHP, they say, that’s an Apache problem, and send them back to #apache. This is very irritating behavior, and results in a lot of frustrated people with unanswered questions. There are indeed questions which are, strictly speaking, Apache questions. However, when they are configuration issues which would necessarily be more familiar to frequent users of PHP, it would be courteous if they were to be willing to handle those questions.

The third issue is one on which, obviously, a lot of people disagree with me. I find the PHP documentation deeply irritating. The model that they have chosen, which I call the “Scripture with commentary” approach, works kinda like this. Someone – the authority, one presumes, writes a brief piece of official documentation. Then dozens of the masses write additional commentary as addenda to that official documentation. These comments might be correct, or they might not. Who’s to know? There doesn’t seem to be any official method for resolving those comments back into the official documents. So you can’t actually know which bits are true, and which bits are uninformed ignoramuses. Then, too, there are a lot of heretical remarks, which simply criticize or complain. These are not only unhelpful, but they distract from the main flow of the truth, and so further serve to confuse the issue.

However, I should say that the PHP docs get a lot of acclaim for being wonderful, so there are obviously a lot of people that disagree with me.

Finally, there’s something that amounts to not much more than a pet peeve. The PHP docs recommend the use of AddType to enable php parsing:

AddType application/x-httpd-php .php

That’s just *wrong.* The correct way to do this would be to use AddHandler. Using AddType confuses people about what AddType means. So you should instead use:

AddHandler application/x-httpd-php .php

What’s especially irritating is that both work. But it’s still wrong.

AddType associates a Content-Type with a file extension, and that tells the browser how to deal with a particular data stream. AddHandler, on the other hand, maps a handler to a file extension.

Stated more simply, AddType tells the browser what to do with a file, and AddHandler tells the server what to do with a file. PHP is handled by the *server*, not by the browser, and so AddHandler is more appropriate.

So, you see, none of these are technical objections with PHP itself, but more deal with the community. It’s a shame when technical communities are divided by community issues, rather than technology issues. But it seems that that’s almost always the way of it.

So, once again, for the record, I’m becoming quite fond of PHP, almost in spite of myself. It makes development quick and easy. If one can get past other objections.