Quoderat

[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?

I was listening to Tim Bray‘s excellent talk On Language Creation today at the XML 2005 conference in Atlanta. Tim was talking about creating new XML-based markup languages (summary: “please don’t”), and in passing he mentioned the must-ignore/must-understand design pattern. For the first time, it occured to me that this pattern has a serious flaw.

The pattern

The pattern works this way: you want to let people extend your XML-based language with new elements, and you want to allow forward-compatibility so that systems don’t break if or when you upgrade the language, so it’s usually a good idea to let applications simply ignore what they don’t understand (as is the case with HTML). That’s called must-ignore. For example, if your application sees this XML document

<record>
 <a>xxx</a>
 <b>xxx</b>
 <w>xxx</w>
 <c>xxx</c>
</record>

but it does not understand the w element (maybe you added it to hold extra information for a different application), it will just pretend that the w element wasn’t there, and might process the document as if it read

<record>
 <a>xxx</a>
 <b>xxx</b>
 <c>xxx</c>
</record>

On the other hand, if w contained some kind of crucial information that would change the application’s processing — say, by reversing the outcome or specifying an essential prerequisite (“turn off the oxygen first“) — it would be better to have the application quit and report an error instead of chugging on ahead. That’s called must-understand. Some specifications, like SOAP, actually specify these rules inside the XML instance on an instance-by-instance basis, but most simply frame them in general terms in the specification.

The problem

I realized today, however, that there’s a huge problem with this approach: must-ignore and must-understand are properties of a processing model, not a markup language. Consider an XML language for a business report: if I designate an element as must-understand, what do I really mean?

1. An application must understand this element to copy this information into a database?
2. A search engine must understand this element to index it?
3. A formatting engine must understand this element to generate a PDF?
4. An XML editing tool must understand this element to open the document?
5. An XSLT engine must understand this element to do a transformation?
6. An archiver must understand this element to save the report for auditing purposes (say, Sarbanes-Oxley requirements)?

Each of these represents a different processing model for the same XML document. The must-understand and must-ignore constraints will likely be different for each one, so they’re obviously not properties of the XML-based markup language. Some XML languages, like SOAP and Atom, are specified explicitly as parts of protocols, so the must-understand/must-ignore constraints are part of the protocol specification, but even then, once you have XML, you never know what clever things people will decide to do with it.

My creaky little Piper Warrior has been grounded since a lighting strike (while tied-down on the apron) back in July, but the engine’s finally back from overhaul, and I plan to be in the air soon — just in time, in fact, to sputter my way down from Ottawa to Atlanta to speak at the XML 2005 conference. I’m planning a 7-8 hour flight down if weather permits, with stops in Watertown NY (to clear customs) and in either Pittsburgh PA or somewhere in West Virginia to refuel. I flew myself to XML 2003 in Philadelphia as well, but that was a much shorter (and non-stop) flight.

Is anyone else flying to the conference in a small plane? Perhaps we can set up an informal general aviation BOF. I’m looking forward to seeing you all there — even the non-pilots, of course.