Month: August 2006

Death by Algorithm!

By Evan — — Science

My old college buddy Dinesh pointed me to the blog of a company, D-Wave, that is trying to make quantum computers commercially available. That statement alone nearly triggered my brain’s Quantum Computing Bullshit Detection Nodule,[1] but Dinesh says that he’s met some of the employees and he thinks they might be the real deal. They’re trying out an alternative approach to quantum computing called adiabatic quantum computing, which they believe is more likely to meet with success than the “traditional” approach. It’s a hard problem, and I wish them luck.

Linked from the D-Wave blog, there’s an interesting paper on arXiv called “NP-Complete Problems and Physical Reality” [PDF]. It’s a more layperson-friendly piece than your average physics journal article, but I still only understood a small fraction of it. This math-y stuff is getting harder every year. Still, I thought it explored some fascinating, if somewhat deranged, physical concepts. I particularly liked the discussion of time-travel computing and its close relation, “anthropic computing”:

“There is at least one foolproof way to solve 3SAT in polynomial time: given a formula phi, guess a random assignment x, then kill yourself if x does not satisfy phi. Conditioned on looking at anything at all, you will be looking at a satisfying assignment! Some would argue that this algorithm works even better if we assume the many-worlds interpretation of quantum mechanics. For according to that interpretation, with probability 1, there really is a universe in which you guess a satisfying assignment and therefore remain alive. Admittedly, if phi is unsatisfiable, you might be out of luck…”

1. Conveniently nestled against the larger and more highly evolved Nanotech Bullshit Detection Nodule.

Why Oh Why Does Documentation Software Suck?

By Evan — — Tech

I find myself this Saturday in the possession of a half-full pitcher of mojito. This is something of a problem, given that I need that very pitcher to make mojitos for tomorrow‘s Sunday barbecue. So I have been doing my best this afternoon to rectify the problem. I only bring this up so that if this post seems less coherent than usual, it’s because of the Demon Rum. In vino veritas, and all that.

So. In the course of my job, I need to produce documentation that falls into these basic types:

  • API documentation: a terse reference for the classes and methods available for a particular C++/Java/PHP/whatever library.
  • Man pages: a terse reference for the commands and options available for a particular command-line tool.
  • User guides: conceptual information and examples, written around the relevant API documentation and man pages.

And I need to produce said documentation in the following formats:

  • HTML: the primary format for modern documentation. At my very first job, we produced our documentation as very nice perfect-bound 7″x9″ manuals using Framemaker. That era is long gone.
  • PDF: in case someone needs to print the documentation.
  • troff: man page format, suitable for installing into /usr/share/man/ or wherever man pages go. To be honest, I’m somewhat confused about the difference between troff, nroff, and other *off variations. But I suppose I shouldn’t worry my pretty little tech writer head over such things.

For engineering documentation, I don’t think these types and formats are all that shocking. There are thousands of writers and engineers who are faced with the same problem every day. And yet there is no documentation technology that can handle all of these documentation types and output formats seamlessly. None.

AuthorIT, Framemaker + Webworks, and other mid-range tech writing tools can at least produce output HTML and PDF. All of these tools are Windows-only. All use a proprietary binary format. None handles man pages and source code-generated API documentation. (We won’t even mention Microsoft Word, which still hasn’t figured out how to do ordered lists consistently, or handle documents longer than 100 pages.)

The only toolchain I’m aware of that even comes close is Docbook. It’s text/xml, so it plays nicely with UNIX. It doesn’t require an expensive client to edit. It can produce output in myriad formats, including HTML, PDF, and man pages. It’s open source. It’s modular (with XInclude). It is the only documentation tool chain that even approaches the holy grail of user guides, API guides, and man pages.

Except… There’s no such thing as “out-of-the-box” Docbook: you need to pick your editor, XSLT processor, FO processor, and template customizations, and there is very little guidance on how to do this.

Except… the default HTML output looks like something out of 1993. Basically, the output is nicely-marked up semantic HTML with no CSS whatsoever. Which is fine, except that this means you’re going to have to sink some time into making the HTML look pretty.

Except… PDF output is really buggy, mostly because the major open source FO processor is still in beta status. Not that I blame them — XSL-FO is hard, and typesetting in general is really hard. But the alternative is to buy a commercial FO processor for $4000/CPU… grrrr…

Except… in general, source code documentation generators do not integrate with Docbook. For Java code, there’s a Javadoc doclet that produces Docbook (yay!). For PHP code, phpdocumentor can generate Docbook natively (yay again!) But for C++, Perl, Python, and other languages, you’re screwed.

Why oh why does documentation software suck?

Welcome to Mirkwood; Here’s Your Badge

By Evan — — Culture

Although my job has been great so far, there are a few minor issues. I once thought that the greatest danger was fellow employees who can’t park. But now a new threat has reared its ugly head — spiders!

Admittedly, the common California garden spider isn’t quite up to the standards of the horror show that we refer to as “Australian wildlife”. But they sure look wicked, and there are lots of them. Most of them have freaky markings on the legs, and all of them have bloated, distorted abdomens. I’m not sure why the spiders around my neighborhood look nothing like the spiders down at work, but I’m guessing that the latter are benefiting from their proximity to the marsh, and an abundant food source. Moths, flies, butterflies, small joggers… you name it.

Last year the spiders were bad, but this year, they’re getting organized. Walking around the trails behind campus, I’ve found shrubs and reeds completely cobwebbed, with a dozen or more spiders all sharing the same web. I didn’t think spiders could do that. A few weeks ago I brought my concerns to my coworkers at lunch:

Me: So in conclusion, there are tons of giant spiders out there in the marsh, living communally. Aren’t you a little freaked out by that?

Coworker #1: Oh wow, so you mean that we’re surrounded by Communist giant spiders?

Coworker #2: Jeez, what could possibly be worse than Communist giant spiders?

(pause)

Coworker #3: Married gay giant spiders?

Incidentally, I’ve heard that over the last couple of years, gay marriage has been polling very well in the spider community, among males at least…

Literary vs. Genre, Explained Using Pie

By Evan — — Writing

I like pie.

In particular, I like key lime pie. There’s really nothing like a good slice of key lime pie. Don’t believe me? Have some! Try some! Key lime pie is delicious.

This is not to say that all key lime pie is good. In fact, the great majority of key lime pie is made from cheap artificial ingredients. More often than not, it’ll be colored radioactive green. This is a real pet peeve of mine. Do people think key lime pie is supposed to be radioactive green? Do the manufacturers of the pie just not care either way? Oh, well. Even if 90% of the key lime pie out there is crap, that means 10% is still scrumptious… you just need to know where to find it.

Naturally, there are many people out there who don’t like key lime pie. “I only like strawberry pie,” they say. Or, “I like all kinds of pie, but key lime pie, not so much.” Or, “You know, I don’t really like pie at all.” Maybe they’ve never had key lime pie. Or maybe they tried key lime pie and hated it — probably because they ordered the radioactive green crap that you get at Denny’s. Maybe they don’t know that there’s good key lime pie out there. But that’s okay! You can’t run around forcing people to try key lime pie. Key lime pie is delicious, but obviously it’s not for everybody.

Although most people have a live-and-let live attitude when it comes to pie, there are some notable exceptions. The most interesting case is blueberry pie. Certain fans of blueberry pie have decided that not only is their personal favorite the only pie worth eating — that’s not so unusual — but they’ve gone so far as to rename their favorite pie as “goodberry pie”. Notice how clever this is. The intrinsic superiority of goodberry pie is, shall we say, baked in to the name itself.

This branding effort has proved remarkably successful. Many pastry chefs and restaurants proudly proclaim that they only make goodberry pie — and is there any other kind of pie, really? The idea that everything other than goodberry pie isn’t worth eating has spawned an entire industry. Eminent university professors who teach Pie Analysis and Pie Creation, critics at the New York Times Pie Review and the London Review of Pie, they all treat goodberry pie as the only “serious” pie.

And this makes fans of goodberry pie perfectly happy. After all, part of the appeal of being a goodberry pie fan is being able to think of yourself as a goodberry pie fan: someone who is sophisticated enough to know that goodberry pie is the only pie worthy of mention. If you press a goodberry pie fan, they might sheepishly admit to eating key lime pie or strawberry pie, but only as a “guilty pleasure”. If you are a serious pie consumer, you are supposed to stick monogamously to goodberry pie and not pollute your palate with other, naughty kinds of pie. Goodberry pie is a harsh mistress.

All this chest-thumping over goodberry pie would be harmless, except that the goodberry marketing campaign has confused a lot of well-intentioned fans of other kinds of pie. After all, the word “good” is right there in the name of the pie! If key lime pie were any good, wouldn’t it be called “good lime pie” or something? Some fans and creators of key lime pie have absorbed this marketing message to such an alarming degree that they have developed a full-blown inferiority complex. “Most key lime pie is gross and nasty and radioactive green,” they say, correctly. “So how can we make ‘Goodberry Key Lime Pie’?”

But this is asking the wrong question! The right question is, “How can we make better key lime pie?” You can’t blame people for forgetting that like all other pies, 90% of goodberry pie is just awful — after all, the goodberry marketing industry exists to obscure this very point. But rather than bemoaning the fact that key lime pie is not goodberry pie, it would be better to spend our time examining the universal qualities that make all pies delicious. Fresh ingredients! Love and care! A thin, flaky crust! The very best goodberry pies have plenty to teach us, but the end goal is not to smush goodberry pie and key lime pie together: it’s to produce the very best key lime pie we can.

I like pie.

Is Our Fantasy Readers Learning?

By Evan — — SF

Charles Stross, “Genre neuroses 101“:

“Finally, there is the blasted heath that is fantasy. At least the two decade long post Lord of the Rings hang-over is mostly over, and the post-movie-trilogy bean fest has faded somewhat. There’s some really interesting stuff going on there (paging Paul Park, Paul Park to the white courtesy phone — or Steven Brust, at a pinch). But fantasy is, almost by definition, consolatory and escapist literature. Pure fantasy doesn’t really tell us anything about the world we live in, and I fail to discern any huge new movements sweeping the field as symptoms of the cultural neuroses of one country or another.” (emphasis mine)

Two problems with the sentence in bold.

First, fantasy is not “by definition” consolatory and escapist. Not even China Mieville believes that. It is trivial to come up with counterexamples.

Second, why is “consolatory” fantasy so obviously inferior to “unsettling” fantasy? I can agree that fantasy that rattles our sensibilities can be excellent. But saying that excellent fantasy must rattle our sensibilities, that’s not qualitatively different from saying that all excellent fantasy should Teach Us Something. Ugh. Look, I don’t mind if you enjoy attempting to OMG R0X0r OUR W0rldvi3w!!!11one1!!, but please, don’t assume that’s the end-all be-all goal for fiction.

Oh, and another thing. “Pure fantasy doesn’t really tell us anything about the world…” Umm, if this is a reference to fundamentally aphysical nature of fantasy, please do keep in mind that 98% of SF, even “hard SF”, is equally aphysical. Those “nanobot/Singularity” stories that are so hip these days? They’re as grounded in reality as the latest offering from Laurel K. Hamilton. Not that nanobot stories can’t be fun and all, but if you’re actually taking them seriously, well, that faint murmuring you’re hearing is the sound of a thousand condensed-matter physicists snickering.

Lloyd Dobler meets the 21st Century

By Evan — — Culture

Random web page #1: “Bait and Switch” by Jennifer Ouellette (via “You are Not Lloyd Dobler” by Chad Orzel):

Come to think of it, rent Say Anything for your date, and chances are you’ll win major points. Most women of my era consider Lloyd Dobler (John Cusack’s character in the film) to be the archetypal Romantic Ideal; we still get teary remembering that scene where he holds up the boombox outside his true love’s bedroom window, playing Peter Gabriel’s “In Your Eyes” in order to win her back. *sniff*[1]

Random web page #2: “Women Love Gadgets, Survey Shows“, Yahoo! News UK

The research reveals that despite our supposed “best friend” relationship with diamond, most women (77 per cent) would rather have a big-screen plasma TV than a solitaire necklace. Slightly less surprisingly, a weekend away in Florida also lost out to the prospect of a new plasma TV, with 56 per cent saying they’d go for the goggle box, given the chance.

What can we conclude from this? If you want to patch things up with your girlfriend these days, you need to show up at her house with… an iPod Nano pre-loaded with Peter Gabriel’s “In Your Eyes”?

1. Chad Orzel’s rejoinder: “Absolutely under no circumstances should you rent Say Anything, or any John Cusack movie from the 80’s, for one simple reason: You are not Lloyd Dobler. And you can’t hope to compete with Lloyd Dobler, so don’t even let it come up.”