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.

Anatomy of a scam

The more I think about it, the angrier it makes me.

Someone tried to commit check fraud on us this morning, and used one of my wife’s paintings as the bait. They initially contacted my wife via her Etsy store, and offered to buy one of her paintings. The email had a number of red flags in it, but we were excited at the prospect of selling one of her paintings, and forgave them.

1) The email was written in barely-literate English.
2) The buyer claimed “I have my own shipping company, so you don’t need to worry about that.”
3) The buyer refused to use Etsy-approved payment methods, but offered instead to send a cashier’s check.
4) The buyer didn’t actually want any particular painting, and suggested that we just send three and let her pick.

#4, by itself, is not only a red flag, but profoundly insulting. Maria’s paintings, in addition to being beautiful, are intensely personal. To say, oh, “I don’t care, any one of them is fine,” indicates a disregard to the art that is just rude.

But, we wanted to make a sale, so we took the bait.

After a few emails, the scam became more apparent. How it works is that they’ll send us a check for more than the purchase amount, and we’re to use the excess to pay for shipping. The buyer’s “personal shipping company” will show up at the door to collect the goods, and we pay for shipping with the excess in the check.

Later on, when the check is discovered as a forgery, we’re on the hook to cover the cost. At that point, the buyer has our valuable painting, as well as the excess funds, and it’s all come out of our bank account.

As soon as the bluff was called, the buyer vanished, and even deleted her Etsy account.

So, the moral of this story is that if the above happens to you, report it to Etsy (or whatever other vendor you’re dealing with) first, and don’t bother responding to the buyer. If a buyer tries to route around either the established payment methods, or the established shipping methods, it’s probably a scam. If the buyer offers to pay more than the purchase amount, and then have you reimburse the excess in any out-of-band way, such as Western Union, a third-party shipping company, or sending it to some off-shore entity, that’s the mechanism of the theft, and the purchase item is just a front.

I think it’s this last thing that offends me so much – that Maria’s lovely art work would be nothing more than a prop in an act designed to rob from us. Absolutely disgusting.

On the bright side, arrests for money order fraud are apparently on the rise, according to various websites I read this morning. Do your research, and, most importantly, if you have any reason to suspect that a transaction is fraudulent, go ahead and assume it is, and report it to any appropriate agency, the website you’re doing business through, and the ISP of the fraudulent buyer.

The Margin Is Too Narrow