Tech Writer’s Blues

When you finally finish the first draft of a technical manual, you can’t help experiencing a sublime feeling of accomplishment.

And there’s nothing that deflates this feeling faster than wasting an hour babysitting the copy machine, waiting for the inevitable paper jam or system crash or whatever. Ugh. It’s all so mundane and tedious. Sometimes I try to pass the time by imagining that the process is… well, more epic or something…

Three Drafts for the QA team, on whom one can rely,
Seven for the Engineers, who do naught but bitch and moan,
Nine for the Managers with deadlines nigh,
One for the VP on his dark throne
In the land of Marketing, where the shadows lie.
One Manual to rule them all, One Manual to find them,
One Manual to explain it all, and at the Kinko’s bind them.

Nope, that didn’t really help.

Who Really Has the Time?

Do not adjust your monitor. We’re back to our regularly scheduled style sheet. Buckle your seatbelt, Dorothy, ’cause the Matrix-themed style sheet is going bye-bye… Sorry! Sorry. I can’t help myself.


I just want to say for the record that working on two books at once is not easy. You go in to the office, crank away on manual #1 for eight hours. Then you return home, wolf down some food, and put about three more hours into manual #2.

Then you sit down and write a smashing journal entry. Or not, as the case may be.

I suppose I shouldn’t complain. Writing for eleven hours a day is draining, but it sure beats digging ditches for eleven hours a day. Don’t get me wrong, I like exercise and fresh air and all that. It’s just that I still don’t know how to swing a pickaxe or shovel dirt without doing bad things to my back, despite my father’s hours of patient instruction on proper pickaxe-swinging techniques.

This is why I’m glad I live in the world of today, rather than the world of my ancestors. I just don’t think I’d do very well in a world where my survival depends on coaxing potatoes out of the frozen Eastern European soil. Oh, sure — maybe I’d have been lucky and been born a rabbi’s son, in which case I would have spent my youth happily ensconced in shul with nary a potato to be seen. Also, let’s not forget that if you were the rabbi’s son, the chicks really dug you. (“Chava! Have I got a match for you!”) Nice work, if you can get it.

But more likely than not, I’d be forced to show off my potato-hoeing skills on a regular basis. This makes me very glad that I live in a society that values other skills also. Somehow I think drawing yourself up and proclaiming, “These are not the hands of a field worker! These are the hands of an artiste!” just wouldn’t cut it on the shtetl. It didn’t cut it in my Dad’s backyard, that’s for sure.

Anyway, we’ll see about being a little more regular about these here journal entries. Coming up next: the real, live, gritty, ripped-from-the-headlines, no-holds-barred story on how I’ve so far narrowly avoided becoming a lawyer. This year, anyway. Lawyering… now there’s another profession that wouldn’t have been so helpful on the shtetl. I mean, I’m sure the marauding troops of the Tsar would have wanted to read all those strongly worded briefs and injunctions and whatnot. But hey, when you’re galloping through the village with saber in hand… who really has the time?

Low Expectations

Look out — it’s the end of the semester, and mild-mannered law professor Jeff Cooper is on a rampage!

Hulk SMASH puny exams! Hulk SMASH students who didn’t listen to Hulk in class all semester! Hulk SMASH!!

Ah, brings back those sweet, sweet memories of grading Introductory Astrophysics. And people wonder why the grad school dropout rate is so high.

So I finally caught The Matrix Reloaded yesterday. I liked it quite a bit — the action was superb, and the plot as a whole was a bit darker than I expected. Sure, the dialogue could have used some work, as others have pointed out. Unfortunately, most of the negative reviews that did so are essentially copy-and-paste jobs from the venerable SF Action Movie Review Template:

  1. Complain that the plot was “confusing”.
  2. Mock the dialogue savagely.
  3. Give a cursory nod to the action sequences. Or not.
  4. Make some not-very-nice generalizations about SF. (Optional step; extra credit.)
  5. Throw up hands, declaring the movie to be “critic proof”. “Go have your fun, dweebs!”

In short, little to be learned here.

By far the strangest review came from AintItCoolNews, where the reviewer is apparently upset that The Matrix Reloaded had no werewolves or vampires. I rushed to go read the AICN review because another article had mentioned this in passing, and my first instinct was, “Poor guy. I bet he’s been misquoted or taken out of context.” But no, the first article was absolutely correct. The AICN reviewer does indeed go on for several paragraphs about how angry he is that there were no werewolves. Or vampires. For the record: while The Matrix Reloaded had its share of deficiencies, a lack of werewolves and vampires was not among them. The reviewer was also very upset about a major plot event that as far as I can tell occurred only in the reviewer’s imagination. One would think a fanboy site would be more plot-detail-oriented, but one is, as usual, quite mistaken.1

The most on-point “negative” review I found was by Stephen Hunter of the Washington Post. Hunter doesn’t hate the movie, but at least he understands the plot and is thus able to separate the good from the bad in a coherent manner. A major step forward.2 Sure, I can quibble with some of Hunter’s complaints, such as his dislike for the “Burly Brawl”. (Personally, I thought the fight really picked up when Neo picked up that pole and started swatting the Agent Smiths around.) But I can’t disagree with Hunter when he says:

Alas, up front, too much time is spent on internecine Zion politics. Really, who cares, especially when expressed, ? la “Star Wars: The Attack of the Clones” and every movie ever made about Imperial Rome, in a rhetorical style that might be called High Fructose-Emulsified Purple. “The Council has asked me to speak tonight at the temple gathering,” intones old Anthony Zerbe in stentorian voice, in a toga, or is it a breechcloth or a nightshirt? Really, this never works, here or anywhere.

No, indeed it doesn’t. Heck, not even the Imperial Romans spoke in High Fructose-Emulsified Purple, as Julius Caesar’s own writings make clear. Which begs the question… why spend so much time and care crafting the stunts and fight scenes and costumes and then totally blow it on the politics?

The answer is obvious: it’s my fault. Or rather, my fault along with everyone else who declares their willingness to shell out nine bucks for the stunts and special effects alone. We’re victims of our own low expectations. At this point I should cry, “We should expect more!” But that sounds very movementarian to me, and I’m already getting a headache. I guess if we want a fusion of good wire-fu and good political dialogue, we’d better write and produce our own damn movies.

1. By now you might be scratching your head and wondering, “What on earth were you doing reading an AintItCoolNews review?” And you’d have a point. My only defense is that AICN is one of those habits wherein you have to endure numerous painful experiences before (hopefully) growing out of the whole thing. Like binge drinking, or Slashdot.

2. Ah, the Washington Post Style section… between Stephen Hunter and Carolyn Hax, they’ve almost made up for Hank Steuver.

Damn, it’s a very exciting time

Goer: “What are you trying to tell me? That I can dodge control characters in comments?”

Distler: “No, Evan. I am trying to tell you that when you’re ready… you won’t have to.”


As you can see, we1 here at are eagerly anticipating the arrival of the new Matrix movie. I don’t particularly care about the alleged philosophical ruminations of The Matrix, all of which have been examined at length by earlier philosophers and writers. At best we can say that The Matrix has tied up these concepts and presented them in an appealing package. Which is something, at least.

Nope, I’m there for the action. I want to see Mr. Anderson wiping the floor with a hundred Mr. Smiths. I want to see Morpheus battling the Twins. Most of all, I want to see Trinity dealing out destruction while clad in black vinyl. Some might roll their eyes, thinking the black vinyl outfits to be hackneyed and cliched… faux cool. Hey, I’m just sayin’, I think Carrie-Anne Moss makes it work.

Finally, I apologize for the new, temporary, Matrix-themed style sheet.2 Unfortunately this site does not provide a style sheet switcher, so I’m afraid that if you don’t like the new look, you’re going to just have to suffer for the next couple of weeks. Please don’t be angry with me. Instead only try to realize the truth: there is no style sheet. Then you’ll see that it is not the style sheet that changes, it is only yourself.

1. Meaning, of course, “me”.

2. If you don’t see any difference… then as Zeldman likes to say, “Kindly reload.”

Look Ma, Another XHTML Post

The X-Philes grow ever larger. It’s become clear that I need to make some clarifications in how the tests work — that I have to state a couple of things explicitly, and that I might need to tighten up the rules to close some loopholes. In the meantime, we muddle through, as we must. Of particular interest in the latest batch: James Graham, a UK physics student who is embedding MathML in certain pages on his site. (Click to advance through the slides on the MathML page.) Also we must give due respect to St. Raphael Academy, which might very well be the most techologically advanced secondary school website ever. Certainly it beats the pants off of my alma mater’s site, which has lovely bordered frames, scrolling headline text courtesy of the <marquee> tag, and no DOCTYPE, presumably to spare us all from the horror. Of course it is a cash-starved California public school. I blame Gray Davis personally.1

I’ve also added a “Useful Reading” list to the Markup section. This list constitutes a small fraction of the external articles and documents that have been instrumental in shaping my thinking on XHTML and web standards. Of course I can’t begin to list all the articles I’ve read, nor can I provide access to all the personal emails and comments I’ve received of late. My thinking on this issue is still evolving. Still pulling things together. More to come.

1. Apparently so do others. Some people take their school’s website design awfully seriously.

The X-Philes

Whoa, a cluster bomb? I hope not! Sounds dangerous.

Well, it has been rather busy around here. I’ve decided to collect all posts that are even vaguely markup-related and display them in a central repository. I’ve also included a list of sites that pass the XHTML 100 test suite. Again, we’re only testing validation and MIME-types. I’m purposefully ignoring Test #4, the “Why Are You Doing This” Test. You could be one of those rarified individuals that has actual technical reasons for using XHTML. Or you could be doing it for “softer” reasons: for political advocacy, as a personal learning experience, or simply to prove to yourself that you can do it. It’s all fine as far as I’m concerned.

Note that I tried to add the W3C Markup pages to the list, but failed. The main page validates as XHTML 1.0 Strict and provides the proper MIME-type to Mozilla. However, the second link I happened to grab is valid but serves up text/html. Ditto for the validator.1

The only downside is that on our sidebar we have to say goodbye to guest-blogger Byron Kubert. Byron’s adventures in Norwegian Viking School were gripping, but now he’s back in the States, and he hasn’t posted in months. He’ll still be accessible from the front page, though.2

Final note: I’d like to offer particular congratulations to stalwart young U.K. computer scientist Thomas Pike and his comrade and countryman, Thomas Hurst. Both of them serve up their pages as XHTML 1.1 to browsers that accept application/xhtml+xml and HTML 4.01 Strict to browsers that don’t — tags and everything. Now that, my friends, is real content negotiation. Gentlemen, I salute you.

1. On the plus side, you can validate the validation of the validator. What fun!

2. It’s a good thing Byron spent more time sailing ships and less time learning how to cleave skulls with an axe, or else I’d be a little worried about demoting him.

Put Your Shades Away for a Minute

Matthew Mullenweg writes that aside from his Photolog, his site passes all three tests in the infamous XHTML 100 survey. It does indeed. I now count one, two, now three sites that pass. Four, if you count the W3C’s own XHTML pages. Goodness, the results are getting less horrific by the minute! So, Matt — like Jacques Distler and Beandizzy before you, I salute your diligence. Matt also jokingly suggests that I start up a webring of invalid sites. To that I respond: a webring that constitutes nearly the entire World Wide Web has to be overkill at the very least.

In the meantime, Phil Ringnalda has posted a nice summary of recent XHTML-related events. Phil’s comments on XHTML MIME-types is basically the following: he knows quite well that text/html has been given the W3C‘s official stamp of glaring disapproval (a “SHOULD NOT“). However, he still chooses to serve up text/html to all browsers for a couple of reasons, which I will summarize and hopefully not mangle:

  1. He’s scraping his own site, and the parsing is easier if he uses valid XML.
  2. If he or someone else posts anything to his site that is invalid, XML-aware browsers will choke.

Therefore, it makes no sense for him to use application/xhtml+xml, because that MIME-type provides no benefit given what he’s actually choosing to do with his XHTML.1

The first part is interesting — I hadn’t considered this possibility. Clearly the oft-touted concept that “XHTML will allow us to use off-the-shelf XML parsers on the web” is an idea straight out of Wolkenkuckucksheim. But Phil is restricting his parsing to a known subset of valid XHTML — his own site. Hard to argue with that.

As for the second part, the someone else is the key bit. It’s hard enough to keep your own XHTML pages valid, but when you have to clean up after other people too… ugh. I don’t have a great answer on this, although Jacques Distler might — he’s been struggling with this issue for weeks now. He’s finally compiled a big piece of the solution all in one place. If you’re an XHTML blogger, you need to read this article.

But Jacques is the type who is willing to hack into the MTValidate plugin to make sure that it validates properly. Not I. All I can do is reiterate what I’ve been mumbling for a while now: XHTML is hard. XHTML was designed to produce code that is stricter and more machine-friendly than its humbler predecessor, HTML. The machines don’t care if the error came from you or from some random person who sent you a Trackback. Either way, the parser will choke.

I’m still “thinking out loud” on this whole XHTML issue, but one thing is becoming clear. Reformulating your site as XHTML requires a major rethinking of everything you are doing. Proceed with caution. Ask yourself why. Phil Ringnalda has a reason: self-scraping. Jacques Distler has a reason: embedding MathML. Put your shades away for a minute: what’s your rationale?

1. I’d argue that Phil is therefore using the correct MIME-type. A) He does have a reason for marking his site up as valid XHTML, but B) he doesn’t really care whether you perceive his site to have any “XML-ness”.

Open Season

Up until four days ago, I had been buying maybe three albums a year at best. But then I downloaded iTunes 4, complete with the unobtrusive little “Music Store” button in the corner. Now it’s open season. So far I’ve bought about six or seven albums worth of music in four days. This constitutes an increase in my rate of buying music of roughly 17,000%. (Ahh, extrapolation.)

So in light of that, it’s a good thing I have a new writing contract. I have to say that I’m quite pleased with my current employers. When I arrived at work on the first morning, not only did I have a phone number and a valid email address, not only could I connect to the web and the intranet, but I could even see printers out on the network. But wait, there’s more… when I opened my desk drawer, I discovered that they had given me a Swingline stapler. Not a red Swingline stapler, but a Swingline stapler nonetheless. It doesn’t get much better than this, folks.

Anyway, in other news: I’ve decided to open up comments on this journal. Here’s why. In the discussion on Jacques Distler’s weblog about my earlier post about XHTML standards compliance, Phil Ringnalda had some thoughtful comments about the worthiness of my “Test #3”, comments that I need to factor in to my thinking. But Phil also commented:

“I wonder how long it will be before those of us with comments enabled think twice about linking to a weblog post without comments, knowing that we will become the comment host for that entry, for our readers.”

For a long time, I’ve specifically disallowed comments on this journal. Partly because I’ve never viewed this site as a “public forum”. Partly because it could end up being a PITA to spend time squashing spam and hateful/racist comments. But mostly because there is nothing sadder than seeing a journal with post after post ending with “Comments (0)”. This is not really a problem for the Alphas, but for the rest of us… well, web logging is self-indulgent enough. We might as well not call attention to the fact that we are shouting out into the wilderness.

Despite all that, Phil has a point. I posted a piece that lends itself to discussion — and I didn’t provide any communications facility other than emailing me directly. This barrier was too high, which is really too bad. I’ve read Phil Ringnalda in the past, and I consider him to be one of the Alphas who really has put some serious thought into standards and their implementation on his site. Not to mention that my thinking certainly hasn’t crystallized on these MIME-type issues yet. So perhaps I missed an opportunity for an educational discussion — if so, that was a blown call.

Thus, an experiment: comments are now open on all subsequent posts. (And on the XHTML 100.) If they turn out to be more trouble than they’re worth, or if nobody is bothering to enter any, I’ll just end the experiment. (Of course, this doesn’t preclude me from padding the numbers by starting arguments with myself.)