Quoderat

[Update: in a comment, Mihai Parparita points out that the Graffiti v.2 was changed for legal reasons, not aesthetic, as explained in a Wikipedia article.]

I got a Palm Z22 for Christmas, to replace my old monochrome Palm Vx. I know that most people have moved beyond Palm, but I like a PDA that’s very small and simple. I make heavy use of Laurie Davis’s outstanding free CoPilot app, especially when I’m in the pilot lounge at some distant airport and need to figure out a new route or recalculate time and fuel for a new upper wind forecast.

Don’t want v.2 for Graffiti …

I love a lot about the Z22, but its one huge, ugly wart is Graffiti v.2, which I had never encountered before now (I’m not sure when it first came in). I have known Graffiti v.1 for years, and can enter it as easily as I touch type. Now, a handful of letters have changed rather arbitrarily, and I keep having to bring up the little virtual keyboard. I’m working on learning the new shapes, and I acknowledge that they would have been better choices for v.1 all those years ago, but what real benefit came from fixing them after the fact? A few engineers might have satisfied their perfectionist aesthetic sense, but thousands of existing, experienced Graffiti users were no doubt gratuitously annoyed, just as I am now.

… or for XML

Let’s not do the same thing with XML and other specifications — sure, we made mistakes writing them, but unless the mistakes are huge, why annoy millions of users with tiny, backwards-incompatible changes? We were forced to create SAX 2.* to support the XML Namespaces specification, though we did our best to maintain backwards-compability, even where we could have made SAX more elegant with a little tweak here and there — the same thing happened with the DOM people. For XML itself, I agree with Tim Bray that it would be convenient to write a specification that combines XML 1.*, XML Namespaces, and the XML Infoset into a single document (as long as nothing else changed — I wouldn’t follow Tim in removing DOCTYPE, as annoying as it is), but otherwise, my motto for specifications is long live v.1!

Kurt Cagle has an interesting piece on the term Open Standard and what, if anything, it means. Rather than a definition, I’m more interested in a shiboleth, a single test that can tell us whether source or a standard (or any other intellectual thingy) is open.

How about this: source code or a standard is open only if it can be forked against the objections of the maintainer. At first glance, this looks horrible — forking is usually considered the worst fate for a standard, a loud non-confidence vote in the maintainer — but that’s the point. Just as a true Democracy (in the modern, non-Athenian sense) allows you to throw out your government, a truly open standard or source code base allows you to throw out your maintainer. If the copyright terms, patents, or anything else prevent forking, then a standard or source code base is not open.

Sometimes a fork forces the original maintainer to get in gear. In the world of source code, XEmacs is an excellent example — while the maintainers of Emacs stubbornly refused to add anything but the most minimal support for modern GUIs, the early success of the GUI-fied XEmacs eventually forced them at least partly into the modern world, however reluctantly. Other times, a fork fixes something that is broken. In the world of standards, XML, with a more agile standards process and sharper focus (at least in the early days), forked and then completely replaced SGML. Linux is a stranger kind of fork, stealing all of the utilities that were being designed for Hurd without bothering with Hurd itself.

Like the ballot box for a politician, the fork — or even the threat of it — is what makes maintainers listen.

[I normally stick to technical issues on this weblog. This posting is about logic, which is sort-of related to tech; apologies in advance to anyone who came here hoping for a short break from personal pontification about current events.]

Over on The Dilbert Blog, Scott Adams has just declared himself the winner of a debate. He asked the following question:

If you think there’s no moral justification for torture, would you accept the nuclear destruction of NYC (for example) to avoid torturing one known terrorist? (No fair extending my question to more ambiguous hypotheticals.)

Most people who commented objected to the question itself; as a result, today Adams declared himself the winner by a knockout and went on to insult his opponents:

… a scary number of people offered comments that were the logical equivalent of punching themselves unconscious in the first round. I don’t need to point them out because they’re somewhat obvious. The point is that most of those people are eligible to vote.

Let’s put aside the issue of torture, and simply look at the question itself. Adams has structured his question so that whether you answer ‘yes’ or ‘no’, you’re forced first to accept the premise that torture is an effective way to get information — in other words, there’s no way to answer the question directly without agreeing with him. This trick is called the Fallacy of many questions — the classic (somewhat disturbing) example is the question “when did you stop beating your wife” — and in a formal debate, it would result in a severe penalty.

To show how this fallacy distorts an argument, substitute a premise that (I hope) no one reading this posting would agree with, and try to come up with a straight ‘yes’ or ‘no’ answer:

If you think there’s no moral justification for murdering children, would you accept the nuclear destruction of NYC (for example) to avoid pushing one live baby slowly into a wood chipper? (No fair extending my question to more ambiguous hypotheticals.)

I do believe that it’s important to debate all issues openly, even touchy ones such as whether torture is an effective kind of interrogation — I believe that the answer is ‘no’ , but in my personal, offline life, I’m not afraid to hear legitimate evidence and reasonable arguments from people who disagree with me. I promise not to introduce any logical fallacies to try to trip those people up.

And I don’t plan an ad hominem attack against Adams either. He seems to be a smart guy, and I enjoy his comics. I’ll look forward to hearing his legitimate arguments on the torture issue.

… and make friends with a technical writer.

Prescriptive grammarians — the ones who argue that the English language should follow a single standard that is both correct and eternal (at least since Fowler) and attempt to impose that standard on people around them — have generally had, at most, a very limited exposure to serious language study. To put it bluntly, folks, we laugh at you behind your backs. Alexander Pope’s famous quip about dim-witted, self-important critics applies here as well:

A little Learning is a dang’rous Thing;
Drink deep, or taste not the Pierian Spring:
There shallow Draughts intoxicate the Brain,
And drinking largely sobers us again.

Technical writers

To a software engineer, the person who often seems the most drunk on shallow drafts of prescriptive grammar is the technical writer. The engineer sends the tech writer a spec, hoping to have the spelling corrected or the prose tidied a bit, and gets back pages covered in red ink, pointing out apparently minor details like ambiguous pronoun reference, comma splices, and colon usage. Sadly, there do exist dim-witted, self-important technical writers, but in fact, most of them are not closet prescriptive grammarians; instead, they are trying to do two things:

1. make the phrases, clauses, sentences, and paragraphs consistent and intuitive in the documentation, just as you try to make the class APIs, GUI components, and interfaces consistent and intuitive in the code; and
2. bridge the gap between engineers, who know a lot about the application, and users, who know little to nothing about it.

Colon usage

As a gift to technical writers, in keeping with the holiday spirit, I’m going to descend a little into the underworld of prescriptive grammar and point out one item that gives tech writers no end of frustration: the use of the colon (:). Take a look at this sentence:

[no]

The three functions are: create, edit, and delete.

Tech writers, copy editors, and English teachers will not accept this use of the colon, any more than a software engineer would accept a method named retrieveAmount beside getDate and getAuthorization. On the other hand, a tech writer would have no objection to this sentence:

[yes]

There are three functions: create, edit, and delete.

Can you spot the difference? If not, here’s another example of colon usage that is unacceptable to most tech writers:

[no]

To enable editing, select:

• authenticate users,
• enable backups, and
• enable page modification.

Without the colon, the example would be perfectly acceptable:

[yes]

To enable editing, select

• authenticate users,
• enable backups, and
• enable page modification.

Here’s an alternative version that is acceptable with a colon:

[yes]

To enable editing, select the following options:

• authenticate users,
• enable backups, and
• enable page modification.

There is a very simple rule of thumb that you can apply: use a colon only if what appears before it could be a sentence on its own. “The three functions are” and “To enable editing, select” cannot stand on their own as sentences; “There are three functions,” “To enable editing, select the following functions,” and Pope’s “A little Learning is a dang’rous Thing; Drink deep, or taste not the Pierian Spring” can.

Best practice for punctuation changes fast, and some day (likely soon), this rule of thumb will be completely obsolete. For now, though, why not make a tech writer’s day a little brighter, and mind the colons?

Bob DuCharme, who is well known in the XML community, now has a weblog. Welcome.

[update: fix affiliations]

I just stumbled on an interesting paper from the IEEE Web Services conference last July, Rethinking the Java SOAP Stack (PDF), written by Steve Loughran at HP Laboratories Bristol and Edmund Smith at the University of Edinburgh. Steve and Edmund believe that JAX-RPC (the main Java-based SOAP interface) takes a disasterously wrong approach for a couple of reasons:

1. automated Object/XML mapping is badly broken for non-trivial applications, and cannot be fixed; and
2. by generating WSDL automatically from Java code, rather than the other way around, JAX-RPC is following a contract-last antipattern.

I agree with them on both points. As I mentioned in my talk at XML 2005, I believe that most attempts to hide XML from developers are doomed because XML really does represent a new way of thinking about information, not just a new way of encoding it. Like the authors, I’ve also noticed that most real-world SOAP implementations end up using document/literal encoding anyway. Here’s a particularly cutting passage from the paper:

We believe that only two categories of web service developer exist: those who are comfortable with XML and want to work with it, and those who aren’t but end up doing so anyway. JAX-RPC provides a sugar-coated wrapping that encourages developers who are relatively unfamiliar with XML to bite. Yet, as anyone who has written a web service of any complexity knows, the XML must be faced and understood eventually. In practise, the task of creating a real web service is made more difficult, not less, by the huge volume of code JAX-RPC introduces into a project.

This is a much bigger issue than JAX-RPC or even SOAP, though. In the end, it points to one of the biggest dividing lines in the XML world, the line between people who think XML is a detail that can be hidden (many big vendors talk that talk) and those who think that it XML is an enabling technology that should be brought into the foreground. Interestingly, the rank and file seem to fall more into the second camp, at least judging by the popularity of raw REST HTTP+XML interfaces among PHP/Perl/Python web site developers.