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.