Weekend Wordsmith

Every week for the last year or so, I’ve posted a word or phrase, and a photo, on the Weekend Wordsmith website. People read the prompt, and hopefully, directly or indirectly inspired by it, write something – a sentence, a poem, a short story – or maybe paint or draw something.

The last 4 or 5 weeks have been pretty awful, with only one or maybe two people responding, and in a few cases, nobody. I’d like to think it’s because he last few months of the year are just busier for people, and they don’t have time. But maybe it’s that I’ve just gotten more and more boring.

There are lots of sites like that – sites that offer inspiration to get you writing, or drawing, or creating. Some of them are more effective than others. The difficulty is keeping them interesting after months or years, but also, on the creative side, remembering to create something every day, even when it’s not fun or easy.

Which reminds me, I haven’t written anything for weeks now. …

YouTube Debut

Everything about this post is amazing, and would be science fiction a few decades ago. Not only can we look inside my wife and see my baby, months before it will be born, but I was able to record that on a device that I can put into my shirt pocket. And, within 20 minutes of making that recording, I was able to show the recording to my sister, thousands of miles away in Haiti, and various other friends and family around the world.
Of course, there’s also the incredibly amazing fact that this little person is in there, and I can listen to the heartbeat and watch the little hands move about. Amazing, and exciting, and terrifying all at the same time. And this kid will grow up surrounded by technology that was barely imagined when I was born.
So, welcome to YouTube, little person. Here’s your debut.

Daily Shoot

For those of you who haven’t seen it yet, you should check out JDD’s new website, DailyShoot.com. He posts a prompt every day, and has inspired some great photos. In the spirit of Pablo Neruda, who wrote poetry about finding the beauty in common things, these photos find beauty in the things that surround us every day, but which we don’t notice.

Apache HTTP Server PDF documentation

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)

Write a better FM

I’ve been delighted to see the “Write a better FM” meme that’s been spreading slowly through various blogs. I understand that I’m to attribute this to Kathy, but I’ve been saying this for years. It’s not sufficient to tell people to Read The Fine Manual, you have to actually listen to the questions that they are asking, and make sure that TFM actually answers them. And, if it doesn’t, then make it better.

This is sometimes as easy as it sounds, but usually isn’t, for reasons that are often non-obvious to people that are in a place to make the world better.

It’s too hard to make the docs better. Those of us who are involved in documentation need to:

  • make it easier for folks to tell us what’s broken
  • be less defensive when they suggest ways to fix it
  • clearly identify our audience and listen to their problems
  • provide clear, correct, efficient ways for them to achieve their goals, rather than telling them that they have the wrong goals

If we don’t, what happens is that a thousand stinkweeds bloom. I’m discovering this the hard way with mod_rewrite. Because the documentation for mod_rewrite is so intimidating, and folks don’t know how to contribute changes to it, instead they write hundreds of HowTos and tutorials and recipes and rants about how to do things in mod_rewrite. These articles are, for the most part, wrong. The ones that work, often do so by sheer chance, and are prone to break if attempted elsewhere. But desperate users take these tutorials, hack on them until they mostly work, and they pass their hard-won ignorance on to other folks.

We could have prevented this, but we chose, by our inaction, not to do so. The problem is *much* harder to fix than it would have been to prevent.

I’m thinking about better ways to allow end-users to tell us that the docs suck, or to suggest improvements. I’ve never been a fan of the PHP methodology, which I have at times called “Scripture With Commentary”, primarily because so much of the commentary is crap. However, it gets the job done, and seems to be the best of the bad. I’d love to hear your suggestions of better ways to collect user feedback, and, perhaps more importantly, incorporate it into the end product.

mod_rewrite and ignorance

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.

But what if they don’t?

A number of Open Source communities have recently published statements discussing appropriate behavior within the community. The obvious question is, what do we do when someone disregards our guidelines?

This question came up during Chris Davis’ talk at ApacheCon, and came up again just now on an IRC channel I frequent. I thought I’d write up my answer before it comes up a third time.

My response actually comes from the Bible, and regardless of your personal religious preferences, this is just good common-sense advice. Here’s the original version:

If your brother sins against you, go and show him his fault, just between the two of you. If he listens to you, you have won your brother over. But if he will not listen, take one or two others along, so that every matter may be established by the testimony of two or three witnesses. If he refuses to listen to them, tell it to the church; and if he refuses to listen even to the church, treat him as you would a pagan or a tax collector.

So, in the context of your Open Source project, I expect you know how to translate “brother” and “church”. Perhaps “pagan or a tax collector” could give us some entertaining contextual translations, but I think that the spirit of the thing is precisely what we’re looking for.

When folks are jerks in Open Source communities, there’s many possibilities. They may be a jerk In Real Life. They may be unaware that they are being jerky. They may be socially awkward, and not clear how they are coming across. They may be intentionally being destructive. They may be a non-native speaker of the primary language of the project, and it’s simply a matter of poor translation. The best way to find out is to talk to them privately. If you can win them over, you’ve saved the project, and you’ve saved this person the embarrassment that was assuredly coming their way. If you can’t, then the community is more important than their potential contribution that you’ll be losing.

If you can resolve community conflict in a way that preserves the dignity of the people involved, you’ll come out ahead. If the troublemaker (“poisonous person”, to use Fitz and Sussman’s terminology) will not be won over, then they should be removed for the sake of the community.

See also: If you have not seen the Poisonous People talk, you should watch it. It has lots of sane, common-sense, practical advice in it.

Cold bad, warm good.

I dislike being cold.

I would much rather be warm than cold.

Yes, I hear you, you hordes of naysayers. You universally pipe up with “At least when you’re cold, you can put on more layers, whereas when you’re hot, you get to the point where you can no longer take off any more.”

This completely misses the point of what I’m saying, and, in a strange way, underscores it. If you put on more layers, then you’re no longer cold, right? Presumably you put on more layers *BECAUSE* you, too, don’t like being cold, and would prefer to be warm. RIGHT?

So please stop telling me that I’m weird because I prefer to be warm. I am a mammal. You are welcome to be a reptile.

That is all.

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?

The Margin Is Too Narrow