The Technical Writer Song

To the tune of “Paperback Writer“:

Dear Senior Engineer, will you review my doc?
It took me months to write, fought through the writer’s block.
Based on a spec by an insane architect
And I need a job, so I want to be a technical writer,
Paperback writer.

It’s the dirty story of a dirty API
Undocumented methods piled high
Just makes you want to pull your hair or bail
It’s a steady job but I want to be a technical writer,
Technical writer.

Technical writer (writer, writer)

It’s a thousand pages, give or take a few,
I’ll be sending it out for a Peer Review.
I can make it longer if you like the style,
I can change it ’round and I want to be a technical writer,
Technical writer.

If you really like it we’ll ship it right away
Forget the editing, we’ll get it out today.
But you must return it, in print or PDF,
I just need a break and I want to be a technical writer,
Technical writer.

Technical writer (writer, writer)

Technical writer – Technical writer
Technical writer – Technical writer

Ehhh, maybe I should keep my day job.

1. It turns out that someone wrote an even better version several years ago, but hey, I didn’t know about it when I wrote this.

2. More tech writer verse by yours truly.

Would You Buy a Used Computer From This Man?

So I’ve purchased a 256 MB SODIMM from a very nice fellow on the Ars Technica Agora Classifieds forum. The extra stick of RAM is really for my kid sister’s iBook, when she gets back for Thanksgiving. Friends don’t let friends run OS X on 256 MB of RAM, folks, and that goes double for big brothers and little sisters.

I’ve also managed to sell my Powerbook to the mother of an old friend of mine, in order to subsidize the purchase of of a brand-new iBook. It was sort of a reckless purchase, but I figured that while I had a desktop, I didn’t really need the SuperDrive, DVI-out, and other Powerbook features, while I did care about the faster CPU, 802.11g card, and better battery life of the new iBook. I suppose I could have scrounged up more cash if I had sold the Powerbook on eBay or Craigslist[1] but it was nice to not have to worry about shipping, and even nicer to know that I was actually going to get a real check from a real, non-deadbeat person. I should note that when I brought over the ‘book so that my prospective buyer could “kick the tires”, she brought out tomato soup and toast and fruit salad for lunch. When was that last time that happened to you on eBay? I’m guessing, never.

Anyway, I think I have figured out my Computing Nirvana. Right now, I have a main desktop and a laptop. Ideally, I would have one machine. Here’s what I’m thinking. By this summer, Tiger should be out, and the Powerbook line should be refreshed at least once. (The Powerbooks are overdue — they’re looking really bad compared to the iBooks right now.) So sometime this summer, I sell the iBook and the G4 desktop and get the bestest 12″ Powerbook I can afford, with Bluetooth, wireless keyboard and mouse, and external firewire drive for backup. Then I can use the Powerbook in closed-lid mode most of the time — but when I want to go work outside, I can unplug the display, pop in the battery, and go. Best of both worlds, I think. And no more syncing between machines. I am done with that.

I’m also looking forward to playing with the new VoiceOver spoken interface. Macintoshes have had nifty voice features for a long time now,[2], but supposedly Tiger’s version is going to be, to use the technical term, way cooler. And that’s a good thing. ‘Cause life needs to be a little more like Star Trek.

1. Particularly Craigslist. I think Apple makes some fine machines, but what are those people thinking?

2. $ say -v Zarvox 'Greetings, meatbag!'

X-Purgation

I was home working on the novel, minding my own business, when suddenly the door crashed in. A dozen men in black body armor swarmed through the splintered doorframe. “FEDERAL AGENTS! PUT DOWN THE LAPTOP!” I raised my hands, confused and frightened. What on earth had I done?

Then a blue eyed, middle-aged man in a charcoal suit strode into the room. I gulped. “Oh my God, it’s United States Congressional Representative Michael G. Oxley, (R-OH)!”

“That’s right, Evan,” Rep. Oxley said. “You’ve been a bad boy, I hear.”

“Those Sports Night DVDs are entirely legitimate,” I said. “Look, I can find the receipt…”

Oxley waggled his finger. “I’m talking about… the X-Philes.”

My blood ran cold. “The X-Philes?”

“Yes,” he said. “We have reports that substantial numbers of X-Philes sites are dead. Or worse, gone back to tag soup.”

I shifted uncomfortably in my seat. “Well… I was kinda counting on self-policing…” Rep. Oxley looked disgusted. The federal agents looked at each other, shaking their heads. “Keee-rist,” I heard one say.

“Son,” Oxley said, putting his hand on my shoulder, “I’m sure this is all an honest mistake. I’m sure you didn’t mean to be so trusting, and that a thorough audit will set this right. Riiight?”

“Y-Yes, sir,” I said, sinking even lower in my seat.

So at great personal expense, my crack team of PricewaterhouseCoopers auditors worked night and day to compile a full compliance report. Of the three X-Philes tests, the auditors only conducted the first test (“The Simple Validation Test”) and the third test (“The MIME-type Test”). As for validating three secondary pages (“The Laziness Test”), I am sorry to report that we simply could not include this metric in the test suite given current budgetary constraints. Look, when these guys are costing $54,000 a week, you have to cut corners somewhere.

Of the eighty X-Phile sites before the purge,[1], twenty-two (27.5%) were no longer compliant. The twenty-two non-compliant sites broke down as follows:

  • Six former X-Philes (27%) invalid and serving text/html.
  • Eight former X-Philes (36%) valid but back to serving text/html.
  • One former X-Phile (5%) invalid but still well-formed and serving up application/xhtml+xml.
  • Six former X-Philes (27%) dead or hijacked.
  • One former X-Phile (5%) hijacked and turned into a porn search engine / linkfarm node, complete with annoying pop-unders.

Which is actually not as bad as I thought… particularly the number of dead and hijacked sites, which seems on the low side.

Over the last year and a half, some X-Philes have been thoughtful enough to inform me about changes in XHTML compliance, and for that, I thank them. I also don’t mind it when sites go dark — that’s just inevitable. These folks are all welcome back at any time. As for the folks who deliberately switched back to tag soup without bothering to ping me, well, that’s a horse of another color.

I had never planned on doing any maintenance of the X-Philes list, and to be honest, I’m not sure how long the list itself will be around. (I’m pretty slow getting back to people on new submissions already — a sure sign of growing boredom/indifference on my part.) Nevertheless, it seems like a yearly purge is probably a good idea. I’m not the XHTML Police, but I would like the list to stay somewhat current.

By the way, this morning I got a phone call from Rep. Oxley. After exchanging some pleasantries, he informed me that next year, Senator Paul Sarbanes would be checking in on me.

“Senator Sarbanes is coming here?” I asked.

“That is correct, Evan. And he is most displeased with your apparent lack of site maintenance.”

“We shall redouble our efforts,” I said.

“I hope so, for your sake. The Senator is not as forgiving as I am.” Then the line went dead.

1. Not counting Beandizzy.com, which has been known to be dead/hijacked for many months. Beandizzy will always maintain its spot as X-Phile #2, for sentimental reasons.

When All Else Fails, Read The Directions

A recent mozillaZine article reports that John Carroll of ZDNet has issues with Firefox’s HTML rendering when compared to Internet Explorer. Specifically, he has set up a test page that uses the overflow property: Internet Explorer displays the page as Carroll intended, while Firefox and Safari don’t. As Carroll describes it,

“I have created a Web page with a fixed position left, top and bottom sidebar that surrounds a scrollable area. All regions resize to completely fill the browser when its dimensions are changed.

To make this work, I have a table which lays out the basic position of the main sections (left bar, top bar, bottom bar, content). I’ve placed a div tag inside the “content” area of the table, setting its width and height to 100% and adding automatic scrollbars by setting the “overflow” CSS attribute to “auto.”

None of this is rocket science. Some might object to the use of tables, which in CSS circles might seem SO 1990s. I couldn’t care less. Tables are easy to use, are immediately intuitive to this old HTML hand-coder, and most important, have existed since the early days of HTML. Regardless of your preferences, there is no reason they SHOULDN’T work.

In IE, the page renders properly. In Firefox, the div tag refuses to size relative to its parent table (and doesn’t provide scrollbars), which causes the bottom toolbar to disappear past the edge of the screen.”

Carroll then proceeds to take Firefox to task for not doing a better job of mimicking IE’s behavior, implementing its proprietary features, and so on. The mozillaZine article retorts that it is Firefox that is rendering the page correctly, and closes with, “We’re not sure if Carroll intends to suggest that Firefox should not only support Microsoft’s proprietary extensions but also do the wrong thing [emphasis theirs] when IE is incorrect.”

I was curious when mozillaZine claimed that Firefox’s rendering was in fact correct. Were they right about that? Carroll’s page is a confusing beast, a weird hybrid of old-skool markup with a sprinkling of advanced CSS layout and overflow rules. Lots of bizarre behaviors we could be bumping into. Fortunately, it turns out the issue is pretty simple.

Let’s begin by eliminating a couple of red herrings. First: Carroll’s impassioned defense of table-based layout is charming, but irrelevant. At first I thought his table structure mattered, but it turns out we can reproduce the effect with only one box element. For its part, the mozillaZine article also snarked that the page “barely validates as the laxest form of HTML 4.0.” Barely validates… like being barely pregnant? Anyway, it turns out that the validation issue is also irrelevant. We could easily construct an XHTML 1.1 + MathML page that exhibits the same problem.

The root problem is in Carroll’s usage of the overflow declaration. What does overflow do? Consider a box that you have constrained to be, say, 50 pixels by 50 pixels. Now let’s say you want the box to contain a long chunk of content, say, all of Deuteronomy. Unless you find a reeeally small font, your content will not fit in the box. That’s where overflow comes in. The overflow CSS declaration defines whether the box should create scrollbars, clip the text, or whatever.

Now consider what Carroll’s page does. He wants to simulate a typical framed layout, where you have a fixed sidebar, topbar, and footer, and a scrollable content pane. So he’s done the following:

  1. Set overflow: auto on his scrollable section. This, he thinks, should cause scrollbars to appear for this section if the content overflows.
  2. Set overflow: hidden on the BODY element. This, he thinks, should force all other sections NOT to have scrollbars on an overflow.

Except there are two problems.

First, Carroll has set the height and width of his scrollable section to “100%” instead of a fixed size. This means that the box automatically expands as large as it needs to be to contain its content. Therefore Carroll’s scrollable section always is large enough to contain all of its content; therefore overflow never kicks in; therefore the section never generates the desired scrollbars, no matter how much “Bah Humbug” text Carroll adds.

Second, by setting overflow: hidden on the BODY element, Carroll has not forced all other sections to not have scrollbars. Actually, overflow: hidden on the BODY or HTML element is a special directive. It tells the browser, “Don’t generate scrollbars for the viewport itself,” i.e. the pane that contains the overall HTML page.

Thus, Carroll has doublefucked his code. Because he doesn’t understand how overflow works, his excess content will always flow down below the viewport. Ordinarily this would be fine — the user could scroll down as usual. But Carroll has told the browser to delete his scrollbars. The end result is a completely borked web page, albeit one that works in IE.

There are three lessons to be drawn.

First, if you want to simulate a framed page, use frames. (Or use position: fixed, if you don’t care about IE.)

Second, IE’s buggy behavior is a major barrier for competing browsers. The typical web designer is not someone who dutifully reads the specs; he is someone with a mental model based on trial-and-error, mystical cargo cult coding. Does it work in IE? It does? Oh good, we’re done. If the alternative browsers can drive their marketshare high enough, this problem will start to go away. Until then, Firefox, Safari, and Opera will always be blamed for IE’s shortcomings.

Third, validation is the starting point for good design, not the end goal. For any web page design, there is an enormous set of possible design problems. Validation reduces this set to a much smaller size, but does not eliminate it. As Carroll aptly demonstrates, it is easy to create a valid page that is totally screwed up. Still,validation is one of the best tools in your toolbox for eliminating basic rendering issues. Unless you are using XHTML (and at most only a couple hundred of you really are), this is by far the best practical reason to validate your pages. Probably the only practical reason. But that’s a story for another day.

1ncr34s3 Y0ur W0rd C0unt W1th N4n0wr1m0!!

A little over a month ago, I mentioned offhandedly to M’ris that I had gotten sucked into NaNoWriMo this year. The point of NaNoWriMo is not to write the best possible 50,000 words in the month of November, it’s simply to bust through the 50,000 word barrier. Try as I might, I’ve never been able to come home from a day of writing and spend a few hours writing some more. So I’m hoping that NaNoWriMo will help me establish new writing habits and leverage the Magic of the Deadline. M’ris, of course, does not need such artificial aids to increase her word output — perish the thought! But she did helpfully suggest some light reading, and after incorporating her suggestions, the final reading list for the month included:

Not to mention a re-read of nearly every book on fiction writing that I own, including titles by John Gardiner, Orson Scott Card, Melissa Scott, Stephen King, and Cory Doctorow (The Complete Idiot’s Guide to Publishing Science Fiction, a steal at $2.99 in the bargain bin). I skipped re-reading Ursula Le Guin (no time, sadly) and Norman Mailer (he was a gasbag the first time around, and seemed unlikely to improve with age).

The tricky part about this project is that while I know how to plan and write a large technical manual, writing a novel is quite different. For example, when writing a technical manual, you never discover halfway through that, “uh oh — the Session Tracking API wouldn’t really ever behave that way, would she?” Then again, engineers seem to enjoy changing the specifications mere days before Code Complete, so maybe technical writing really isn’t so different from fiction writing after all.

Needless to say, the tight deadline means cutting a few corners in the planning process. I suspect that failing to plan in fiction writing is roughly as successful a strategy as failing to plan in technical writing. As I said above, this is not going to be the best 50,000 words I could possibly write. On the other hand, this is not going to be a 50,000 word freewrite either. Wish me luck.

HTML House of Horror: Markup… from the FUTURE!

Last year’s HTML House of Horror brought us the Page of the Damned, and was probably instrumental in bringing support for the MARQUEE element to Safari. What horrors will this year’s page unleash? If ye do doubt yer courage or yer strength, look nae further!

As some of you might know, my career as an experimental condensed-matter physicist ended rather abruptly in 1998. A garden-variety case of grad-school burnout… or at least, that’s what everyone was supposed to think.

The truth is that I was thrown out. When my innovative theories on the nature of spacetime came to the attention of the Institute for Theoretical Physics, the scientific orthodoxy moved quickly to silence me. I was turned out on the street, with naught but a spare cryopump and a broken dilution refrigerator to my name. They called me mad, mad! Fools! I’ve showed them all!

As anyone with even a passing acquaintance with quantum mechanics knows, probing the structure of events at the Planck scale requires tremendous power. Back-of-the-envelope calculations estimate that such experiments would require an accelerator the size of the galaxy, but such old-fashioned “reality-based physics” is no match for faith-based physics, physics forged by pure Strength and Will.

My first, failed experiments in early 2001 did have noticeable effects on the California power grid, and for that temporary inconvenience, I apologize. Despite those early setbacks, I managed to steadily lower power consumption and increase the sensitivity of the device. By the summer of 2003, I was able to probe the seething quantum foam itself. And I managed to confirm my theory that the foam resonates weakly in the wake of electromagnetic disturbances… electromagnetic disturbances from another slice of spacetime.

After another year of tuning, and the development of signal-processing algorithms the likes of which would make grown IEEE Fellows weep, I was able to detect actual electronic signals from the future. It has taken weeks of calculation, but my poor, aged G4 PowerMac has finally succeeded in decoding a fragment of an actual HTTP packet exchange. Look upon the works of the future, ye markup geeks, and despair.

GET / HTTP/1.1
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.3; Windows NT 6.1)
Host: grandpahenry.com
Connection: Keep-Alive

HTTP/1.1 200 OK
Date: Wed, 13 Feb 2008 20:39:26 GMT
Server: Apache/1.4.1 (Unix)
Last-Modified: Thu, 04 Oct 2007 11:18:11 GMT
ETag: "2f51cd-924-381e1af6"
Accept-Ranges: bytes
Content-length: 4211
Connection: close
Content-type: text/html


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 2.0//EN" "TBD">
<HTML>
<BODY background=bassfish.gif leftmargin=0 rightmargin=0 topmargin=0>
<CENTER><b><BLINK><font size=7>Grandpa Henry's Fishin' Page!</b></font></CENTER>
<nl>
<LI HREF="fishing.htm">Fishing main
<LI HREF=rainbo1.htm>Rainbow Trout
<LI HREF=rod.htm>Rods and reels
<LI HREF=spots.htm>Best fishing spots
<LI HREF="grandkids.htm">Cody and Gavin!
</NL>

Well I'm back from taking little Cody & Gavin fishing, and we had a blast! We've got new pictures and more, including little Gavin's <font color="RED">FIRST TROUT</font>!<p>

<BIG href="/troutpics.html">CLICK HERE FOR PICS!
...

Happy Halloween!

Beer and Baseball

Every Wednesday, we all assemble at a local bar before our weekly poker game. Usually the bar is busy, but tonight it was packed. How packed? Packed enough that our regular waitress was nowhere to be seen, and we had to settle for a random server and… ordinary service. The indignity of it all! It’s probably worth mentioning that on only slightly less hectic nights, our regular waitress has been known to greet new arrivals at our table by smiling and immediately setting down a beer from her tray. Someone else’s beer, that is. Now that’s service.

Now, the patrons of this bar are not the most rabid sports fans in the world. Just your typical 25-45ish Silicon Valley types in jeans and khakis and polo shirts. No ‘Sox paraphernalia in sight. And yet… everyone was going wild after every big Red Sox play. Three thousand miles from Boston. Heck, the South Bay is not exactly thick on the ground with people who even pay attention to the American League at all.

Is there anyone outside of New York and its environs who doesn’t despise the Yankees?

Flotsam: The Most Important Political Commentator, Ever

Congratulations to Marissa! M’ris has finished her draft of Sampo, also known as the “Not the Moose Book”, also known as, “the one about Finnish mythology, vacuum-tube computing, and Cold War spies.” Ha, let’s see the reviewers try to slap the Harry Potter label on that one.[1]

Rachel reports that her husband Ben has enrolled full time in the University of Minnesota’s Food Sciences department. He now has labs such as the fudge lab and the angelfood cake lab. Clearly, we are all in the wrong professions. (“Now, titrate the cookie dough with chocolate morsels…”)

Russ calls our attention to… The Freezerator! Quite possible the best garage refrigerator, ever. Jeremy tries to rain on the parade a bit, pointing out that the Freezerator is “…truly the SUV of refrigerators. Anybody else take a look at the ‘Energy guide’? Comparable models span a range of 511-572kWh/year. This one comes in at 770kWh/year.” But that’s Jeremy for you — Mr. Liberal P. McLiberal who is also very liberal. Whatever, Jeremy.

I saw Primer last night. I think the 22-year-old version of myself could have untangled all the causality loops the first time around, but my current brain just couldn’t hold the whole thing together at once. Stupid rusty brain. I don’t feel too bad, though — I saw a couple of middle-aged gentlemen exiting the theater, gentlemen who fairly reeked of “Stanford physics professor”, and they looked pretty dazed too.

Finally, via Wonkette:

Jon Stewart to Crossfire and all other “debate” shows: “Stop, stop, stop, stop hurting America.” History will show that Jon Stewart was the greatest American political commentator of the early 21st century. No pundit on any op-ed page or on any television show comes close.

STEWART: I would love to see a debate show.

BEGALA: We’re 30 minutes in a 24-hour day where we have each side on, as best we can get them, and have them fight it out.

STEWART: No, no, no, no, that would be great. To do a debate would be great. But that’s like saying pro wrestling is a show about athletic competition.

(LAUGHTER)

CARLSON: Jon, Jon, Jon, I’m sorry. I think you’re a good comedian. I think your lectures are boring.

STEWART: Yes.

CARLSON: Let me ask you a question on the news.

STEWART: Now, this is theater. It’s obvious. How old are you?

(CROSSTALK)

CARLSON: Thirty-five.

STEWART: And you wear a bow tie.

(LAUGHTER)

(APPLAUSE)

CARLSON: Yes, I do. I do.

STEWART: So this is…

CARLSON: I know. I know. I know. You’re a…

(CROSSTALK)

STEWART: So this is theater.

CARLSON: Now, let me just…

(CROSSTALK)

CARLSON: Now, come on.

STEWART: Now, listen, I’m not suggesting that you’re not a smart guy, because those are not easy to tie.

Full video available.

1. Although there’s another school of thought that says that if reviewers aren’t trying to slap the Harry Potter label on Sampo, M’ris really ought to be firing her publicist.

2. Also, frist post with MarsEdit!!!1!! MarsEdit is the first Mac weblog editor I’ve ever thought was worth using. Nice work, Brent.

Envy Is So Unbecoming…

A few months ago, an friend of mine from HMC forwarded us all a link to a Channel 9 discussion about Microsoft’s Avalon project, hosted by fellow ’97 alum Joe Beda. The general reaction of the recipients was, “Holy crap, Joe’s gone bald!” I didn’t care about the hair; my reaction was, “Holy crap, Joe’s one of the lead developers on Avalon!”

Fast forward a few months, and it turns out Joe has left his high-profile job at Microsoft, to take another job at Google. I don’t know how high-profile this new Google job is, but apparently it’s important enough to be reported in nationally-syndicated media outlets.

Well, Joe says it’s not all that newsworthy… but come on, can’t you just smell the false humility? I’m all about rooting for my fellow alumni,[1] but this is starting to get ridiculous. To Joe I say, pbbbbhhllt! At least I still have all my hair.

1. I’m trying to think of other HMC grads who are moderately famous in the software world. Bookmarklet guru Jesse Ruderman springs to mind, but these days he’s mainly famous for his interest in porn. The only other one I can think of is Wes Cherry, that dude who invented Windows Solitaire for free when he was an intern. Well, that’s something, at least.