Category Archives: Uncategorized

mod_rewrite book

Back in early 2006 I published The Definitive Guide to Apache mod_rewrite. It hasn’t sold well. It was hardback, and overpriced for such a slender book. Many people have mentioned to me that they think it’s a great book, but the royalties aren’t exactly pouring in.

There are, as with any book I’ve done, many things I wish I had done differently. But the publisher isn’t interested in doing another edition, largely due to the poor sales.

So I’m considering, in 2010, doing a new edition of the book, and distributing it both as a free PDF as well as making it available via my Lulu store. This will give me the opportunity to start with the current book, but then to update it on an ongoing basis, and always have the latest version available. And the folks who want a print copy can get one.

I have no idea whether folks would be interested, but I’m tired of looking at the book on my shelf and thinking how much I wish I’d done things a little differently.

What do you think?

Writing Documentation

Someone (and I now can’t remember who – I think it was Philip Olson) pointed me to Writing Open Source this week, and I’ve been somewhat fixated on it since.

I’ve been writing technical documentation for more than a decade now. 12 years sounds about right. Let’s go with that. I’ve been told I’m good at it, so I keep doing it.

I’ll let you in on a little secret. I don’t tell just anybody this, because they think I’m a freak. I actually enjoy writing documentation. I enjoy figuring out how things work, and then writing about it so that other people don’t have to figure it out. I enjoy catching the first glimmer of the spark of understanding when someone reads what I wrote and gets it for the first time. I love it when people say “Oh! I didn’t realize it was that easy!” and “Why did it seem so complicated before?”

There are precious few places that do documentation well. There’s a number of places where Open Source documentation, and software support in general, typically falls down.

* Tell the user that they’re an idiot, and probably too dumb to use this software. This is done in a variety of ways, and is often abbreviated RTFM, but TFM is often insufficient.
* Pretend that the end-user cares about the architecture of your software. They don’t. They just want to get their job done.
* Fails to distinguish between end-user and developer documentation, and, if there is a distinction, the path from one to the other is left as an exercise to the reader
* Refuses to consider the interrelationship with related technologies, and continually tells the user that “that’s a problem with ProductB” rather than giving them the support that we’re qualified to give.

And many, many others.

As I looked at this website, I became more and more persuaded that perhaps I could help in the effort to write a guide of how to write Open Source documentation – not from the perspective of whether to use passive voice or not, but from the perspective of identifying with your audience and answering the questions that they’re actually asking, not the ones that you feel that they should be asking.

On a related note, during a recent conversation on IRC I suddenly realized that I’ve been working programming jobs all these years because I haven’t been able to find a position that’ll pay me to do what I really love – writing technical docs. I wonder where this realization will take me in coming years.

A Christmas Carol, Jim Carrey version

Warning: Spoilers.

Yesterday we went to see Jim Carrey’s Christmas Carol. It was very disappointing. Given the opportunity to follow in the footsteps of a great book, and add something to the list of great movies that have already been made of this book, he chose instead to add one to the growing pile of cheesy renditions. This one was somewhere below the Muppet’s Christmas Carol, although probably above the Jetson’s Christmas Carol. Patrick Stewart is still by far the best.

When making a lengthy book into a movie, one has to adapt. That’s obvious, I suppose. But the art is in deciding what to cut, and what to leave in. This requires that you actually know the story, and know what really matters in it. Carrey left out several of the most significant moments of the story, and altered a few of the other ones to the point of their being far less meaningful.

Some film makers choose to add stuff in, such as a cute animal companion, or an extra Marley. Sometimes this works, and sometimes it doesn’t. Hint: It works when it’s clear from the start that you’re not trying to do a faithful rendition of the original.

This is where the Carrey version fails, and fails hard. It’s never completely clear whether he’s trying to do a faithful rendition. Some places, it seems that he is. The multiple faces of Christmas Past was not only well done, but really the first time that’s ever been done in a movie. The strict adherence to the script for the majority of the movie, occasionally translating phrases for an American audience, too, made it seem that he was indeed trying to be true to the book.

But then inserted here and there were things either wildly outside of the book – such as a lengthy chase scene, and a rocket trip to the moon. (Huh!?!) And also things were inserted that simply undermined the feeling that we were really visiting Scrooge’s past, such as Mrs. Fezziwig suddenly taking flight during the dance. It’s significant that the two scenes I hated the most from the movie are the ones most prominently featured in the trailers.

And the entire death scene of Christmas Present – well, I’m torn on that. It was a very interesting interpretation of something implied, not stated, in the book. Ignorance and Want were straight out of the 1938 Christmas Carol. But then it got positively weird.

Also missing: The scene where Christmas Present chastises Scrooge for presuming to judge who is the “surplus population.”

Altered: Christmas Present blames the church, rather than Parliament, for attempting to keep places of business closed on Sunday.

And, really, Christmas Present was just … creepy. In the book, Christmas Present is benevolent. Everything about him is benevolent. Yes, he laughs a lot, but it’s jolly, whereas in this movie Christmas Present is, for most of his time on screen, just creepy. He laughs far too much, and at all the wrong times, and is more hysterical than benevolent. To be fair, it’s hard to identify any movie that really gets Christmas Present right. Patrick Stewart does, and, strangely, the Muppet movie does.

While I was very pleased with the start of the movie – Marley was just about perfect – by about halfway through Christmas Past, I started feeling that this was just an opportunity to show off cool new technology. The technology (yes, the new 3D stuff is amazing) was the end, rather than a means to tell a classic story in a new way. And while I was initially fascinated with the rather unorthodox interpretation that the ghosts are just parts of Scrooge himself, this didn’t work for me, and made me feel like they did this just because it’s what they did in Polar Express.

I rather wish that we had gone to see it at the Movie Pub instead, so that instead of the gratuitous 3D, we could have enjoyed a meal.

Light painting

One of the (many) high points of this year’s ApacheCon was that Julian was there, and I got to play with him. He was doing light painting, and his techniques have advanced enormously since the last time I watched him do this.

The night before he was doing the photos, Julian said that I should come up with a word or phrase that I wanted him to try to capture in the painting, and I came up with POET. Here’s what he did with that. And here are the other photos from the week.

It’s very cool having such talented friends.

The Wall

We’re reading the accounts of November 9, 1989 in Berlin, and, in retrospect, it seems almost absurd. A wall? Between two halves of the same city? Ludicrous? But it was *only* 20 years ago, and I remember that day so very clearly.

And, at the same time, almost daring to hope that our kids will see a day when they can look back 20 years and say, really? was there really a wall between the USA and Mexico? It seems so absurd!

It’s amazingly difficult to look at the fence between the US and Mexico (and the lack of one between the US and Canada) and think of it as any different from that between East and West Berlin. I’d really like to believe that we, the people of the United States of America, can arrive at this conclusion within my lifetime. Alas, we seem to be moving, quite rapidly, in the opposite direction.

Happy 10th Birthday Apache

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.

ApacheCon US 2009, days 1 and 2

I’m in Oakland for ApacheCon US 2009, and we’re about to start the first day of the main conference. Monday and Tuesday were for half-day and full-day training classes. Jim Jagielski and I did the two-day Apache web server training class, with him doing day one and me doing day two.

I’ve been fighting off a cold for more than a week now, and by the end of yesterday I had no voice left, which was very frustrating, but the class were understanding and forgiving, and Jim bailed me out for the last hour of the day.

Last night we had the members reception, which was great, as always. Then later in the evening I went down to the San Francisco Perl Mongers meeting, and hung out with Julian for a little while.

We’re now about 10 minutes late for the start of the opening plenary, and … here goes.

mod_rewrite docs rewrite at ApacheCon

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.

Influential in Open Source?

Yes, I have to agree with Grant, the list of the “most influential people in Open Source” is perplexing, at the very least, containing names like Steve Balmer, Scott Mcnealy, and Mårten Gustaf Mickos, while missing the blindingly obvious names like Linus Torvalds, Brian Behlendorf, Michael Widenius, and either Larry Wall or Rasmus Lerdorf (you’ve heard of LAMP, right?) as well as folks like Richard Stallman and Eric Raymond. These folks are *still* the driving forces behind the Free Software and Open Source movements, all these years later.

But, also, as Grant notes, the most influential people in in Open Source are folks like Dries (it’s VERY cool that he’s on the list) and Matt Mullenweg and Owen Winkler and Paul Querna, and any of a zillion other people I could mention, who do the actual day-to-day coding of the projects that really matter, in the sense that hundreds and thousands of websites use them every day to power their businesses and our economy.

Calling a bunch of CEOs the most influential people in Open Source profoundly misses the entire point of Open Source.