Not about the iphone

A classic pundit failure: In 2006 Bill Ray wrote in The Register that the iphone would be a a complete failure. The article has been quoted as pundit failure ever since.

I'm not sure it actually was a failure. Perhaps the editor asked the author to provide a crowdpleaser: Give me lots of pageviews and facebook likes, make our readers' heads nod in agreement, it doesn't have to be factually right. If that's the case, then the article may have been a roaring success for all I know.

I'm going to pretend it wasn't like that, though, because it doesn't suit my purpose with this posting. This is about technical documentation, not crowdpleasing or pageviews. My purpose here is to illustrate a class of mistake in technical documentation. Bill Ray's article is a wonderfully vivid example.

The article has two main points. One of them (about the power of retailers over customers and manufacturers) is irrelevant to technical documentation, so I disregard it. Here's the core of the other point:

The clever design of the iPod stretched into the software — the clean and simple interface is indeed easy to use, and users seem very comfortable with iTunes on their PC. But creating a simple interface for a single function is one thing. Replicating that experience to manage all the functions of a mobile phone is another thing entirely. Mobile phones are not complex to use because of bad interface design, they are complex to use because they are complex devices with a myriad of features.

That's vivid and vague — and wrong, as we all know now.

Much documentation does the same thing, generally using the words simple or useful, and regrettably the simplicity and utility are also not quite real. Here's a way to test.

Ask: Is the subject actually simple? Useful? If it's simple, try writing two more sentences and explain how. Writing two sentences won't take much time, and if it's not possible, maybe the word simple is not the right word... or maybe the function should be redesigned so that its simplicity is the kind that can be explained to humans. If it's useful, try writing a sentence with three examples. That's quickly done if it's true, and if not, the attempt will demonstrate that useful isn't the right word and maybe the error is bigger than just a poorly chosen word.

It's not necessary to include the explanation or examples in the final documentation. Maybe that would be good, or maybe it makes the documentation too verbose. The point of writing them is to guard against mistakes, not to include extra words. Once written you know whether there's a mistake, and can delete the guard if you want.

In the case of that article, myriad features is the vivid and vague phrase. Let me test that with a list. First, what's does feature mean? The preceding sentences say an ipod has a single function, so store, find and play music counts as one. Knowing that, I can make a rough list of a mobile phone's functions: Send and receive calls. Add people to the contact list. Send and receive SMS. Take pictures and copy them off the phone. Send and receive pictures as MMS.

Nowadays some more bundled apps and support for third-party apps would be on the list, but in 2006 they weren't, so that makes five features. Or six, if combining those five features well is a feature in itself. Or seven, if I forgot something.

Five, six or even seven isn't a myriad, so something is wrong. What to do? Maybe just rewrite the paragraph, and argue that the iphone has to fail because even though one feature can be done well, five obviously cannot. Or maybe rewrite entirely and argue that the iphone will succeed. (Always assuming that the goal is accuracy rather than pageviews.)

The five-point list I made would not help the article. It doesn't need to be included, it doesn't even need to be accurate. It's like a unit test for prose: It exists to help deploy correct prose, not to be deployed itself.