The Margin is Too Narrow
Although I've known for a while that it was possible to build the HTTP Server docs as PDF, I never really bothered to find out how. Finally this afternoon I was poking around and figured out how. The latest docs are available in PDF format here, and I'll try to keep them somewhat fresh, if you want to bookmark that.
Apache HTTPd 2.0 docs (pdf - 3Mb)
Apache HTTPd 2.2 docs (pdf - 4Mb)
Apache HTTPd 2.3 (trunk) docs (pdf - 4Mb)
For the last week or two, I've been using Twitterrific. One of its features is that you can watch for all tweets that contain a particular word or phrase. So I've been watching 'mod_rewrite'. The following graph shows the rough distribution of those tweets.
It's distressing to me, as something of a recognized expert on the subject, to see the vast amount of information online about mod_rewrite which is inaccurate, inefficient, or just plain wrong. But people are clearly hungry for any scrap of mod_rewrite info that they can get, since every time another misinformed tutorial is posted, 30 people retweet it as gospel.
Now, some could claim, very justly, that we brought this on ourselves. The documentation is frightening, and announces in the first paragraph that this is not for mere mortals, and has been largely unchanged for over ten years. We've recently done a complete overhaul of the docs, but it might just be too late.
And, of course, another huge force is at work here. Yes, the SEO industry. No, I will not engage you in the debate about whether all so-called "SEO professionals" are snakes and liars. A significant portion of this industry thrives on misinformation and impossible-to-fulfill promises. And many of these folks equate "SEO" and "mod_rewrite", thus indicating a complete lack of understanding of both.
Between these two forces, there's a huge thirst for useful mod_rewrite tutorials, both by people with legitimate need for mod_rewrite, and people who have been told, inaccurately, that they need it. And, unfortunately, for years the Apache docs haven't done that. They haven't offered the examples that people are actually looking for, and they've had that dreadful "ABANDON HOPE" across the front arch.
So, we're working hard to rectify this with the new docs which will include lots of examples, and hopefully address the questions that you're actually asking. But, alas, the nonsense tutorials keep springing up, so perhaps we need some active way to address those, tell you why they're mistaken, and perhaps encourage the authors to correct them in useful ways that will result in the spread of true, accurate, efficient mod_rewrite information, and less of this ridiculous myth that mod_rewrite is a big scary monster.
The Apache Software Foundation is ten years old.
Pretty cool, hmm?
I do a podcast called Feathercast, about technologies and people within the Apache Software Foundation. I do this for a number of reasons.
I love playing with technology, even when I don’t really understand it. Using it is the best way to understand it, and I’ve learned a lot about audio recording in this process, although I’m still far from an expert.
I get to talk with some amazing people, and ask them about stuff that’s truly fascinating.
And I enjoy educating. I like to weasel out the important details and teach people about things that they might otherwise have dismissed as unimportant. I like taking complicated ideas and explaining them in terms that everyone can understand.
In other words, it’s a mixture of selfishness and altruism, as are all worthwhile human endeavors. If we’re doing something entirely for ourselves, that’s no good, but it’s also important to have a passion for something, and for it to be fun.
Coincidentally, these are the reasons that I’m involved in the ASF. They happened in a different order - I got involved because I found an interesting technology and started writing about it. But along the way I’ve met some amazing people - Douglas Adams, Brian Behlendorf, Arthur C Clarke, Sanjiva Weerawarana, Mark Shuttleworth, Ken Coar, Deepal Jayasinghe, Larry Wall, and so many others it’s impossible to list them. Some of these people I’ve come to consider friends.
I’ve also had the opportunity to be involved in amazing technologies that have changed the way we communicate, play, and do business. The Web is, of course, built on generations of advances, and even more amazing things are to come, but it’s been a fascinating ride to be part of that.
Apache, and other open source technologies that I’ve had the opportunity to be involved in, have changed the world, and I got to be part of that, because they are open source, where the willingness to participate is rewarded with the permission to participate, unlike so many other parts of our world. We get to be a part of things that matter, and the barrier to entry is that willingness to participate and make a difference.
It’s a great honor to be a member of the Apache Software Foundation. It’s a badge that I wear with pride, both because I know how hard I worked to achieve it, and because I’ve seen the other amazing things that the ASF has accomplished.
Happy Birthday, Apache. Here’s hoping the next ten years are as exciting as the last ten, and that I get the chance to be even more involved than I have for the last ten.
The plan, (assuming I don't get sidetracked on a million other things, which is what usually happens) is to do a major overhaul of the mod_rewrite documentation during the hackathon at ApacheCon. Please speak up if you have specific comments or recommendations. So far, the outline is something like this.
1) A couple of years ago, I split the "Rewrite Guide" into basic and advanced. This was ill-advised, and the division was stupid. Now it's just harder to find stuff. Going to re-merge those, and then try to do a division based on topic, rather than difficulty, since that's not a particularly useful concept.
2) Rewrite cookbook, divided into categories of, perhaps:
a. redirecting/remapping
b. controlling access
c. when not to use mod_rewrite (aka 'mod_rewrite is obsolete')
d. advanced features
3) Scrap the inscrutable examples. Both the guide and the formal docs are littered with examples that either never happen in the real world, or are done better using some of the built-in functionality of other modules like mod_alias and mod_dir. Scrap those examples entirely, rather than continuing to try to make then scrutable.
4) Rewrite Flags documentation. Started this years ago, and never really finished it. Also, needs to be updated to include the new flags that have been added in 2.2 and trunk.
5) General grammatical overhaul, hopefully with help from Noirin, who has better grammar than all the rest of us put together. (Actually, that's the problem - it was written by all of the rest of us put together, resulting in a mish-mash of styles and voices.)
6) A document about (so-called) S.E.O. uses of mod_rewrite, discussing both the techniques that can be used, and the misinformation that tends to drive the desire to use those techniques. This needs to be handled carefully, because there's a tendency to simply state that all SEO is snake oil - which much of it is - and ignore the topic entirely. But, folks are going to do this stuff whether or not we approve, and it's better if they do it well. At least, that's what I think at this particular moment.
2c, above, is both about stuff that you shouldn't do with mod_rewrite at all, and also some of the new features in 2.2 and trunk that make mod_rewrite unnecessary.
Some people are heroes. And some people jot down notes. Sometimes, they're the same person. (The Truth. Terry Pratchett)