Monday, February 10, 2020

Concerning My Smartphone Agonies

     Subsequent to posting yesterday’s rant, I received a lot of email that echoed the sentiments therein. One piece in particular was rather plaintive. The writer wanted to know why no one writes clear instructions in readable English any longer. It cast my thoughts back to a book many Gentle Readers have read and others have heard about and have said “Yeah, I’ve always meant to read that.” Here’s a long but relevant citation:

     DeWeese brings over some instructions for assembly of an outdoor barbecue rotisserie which he wants me to evaluate as a professional technical writer. He’s spent a whole afternoon trying to get the thing together and he wants to see these instructions totally damned.

     But as I read them they look like ordinary instructions to me and I'm at a loss to find anything wrong with them. I don't want to say this, of course, so I hunt hard for something to pick on. You can’t really tell whether a set of instructions is all right until you check it against the device or procedure it describes, but I see a page separation that prevents reading without flipping back and forth between the text and illustration., .always a poor practice. I jump on this very hard and DeWeese encourages every jump. Chris takes the instructions to see what I mean.

     But while I'm jumping on this and describing some of the agonies of misinterpretation that bad cross- referencing can produce, I've a feeling that this isn't why DeWeese found them so hard to understand. It's just the lack of smoothness and continuity which threw him off. He’s unable to comprehend things when they appear in the ugly, chopped-up, grotesque sentence style common to engineering and technical writing. Science works with chunks and bits and pieces of things with the continuity presumed, and DeWeese works only with the continuities of things with the chunks and bits and pieces presumed. What he really wants me to damn is the lack of artistic continuity, something an engineer couldn’t care less about. It hangs up, really, on the classic-romantic split, like everything else about technology.

     But Chris, meanwhile, takes the instructions and folds them around in a way I hadn't thought of so that the illustration sits there right next to the text. I double-take this, then triple-take it and feel like a movie cartoon character who has just walked beyond the edge of a cliff but hasn't fallen yet because he hasn’t realized his predicament. I nod, and there’s silence, and then I realize my predicament, then a long laughter as I pound Chris on the top of the head all the way down to the bottom of the canyon. When the laughter subsides, I say, "Well, anyway — " but the laughter starts all over again.

     "What I wanted to say," I finally get in, "is that I've a set of instructions at home which open up great realms for the improvement of technical writing. They begin, 'Assembly of Japanese bicycle require great peace of mind.’ "

     This produces more laughter, but Sylvia and Gennie and the sculptor give sharp looks of recognition.

     "That’s a good instruction," the sculptor says. Gennie nods too.

     "That’s kind of why I saved it," I say. "At first I laughed because of memories of bicycles I'd put together and, of course, the unintended slur on Japanese manufacture. But there's a lot of wisdom in that statement."

     John looks at me apprehensively. I look at him with equal apprehension. We both laugh. He says, "The professor will now expound."

     "Peace of mind isn't at all superficial, really," I expound. "It’s the whole thing. That which produces it is good maintenance; that which disturbs it is poor maintenance. What we call workability of the machine is just an objectification of this peace of mind. The ultimate test’s always your own serenity. If you don't have this when you start and maintain it while you're working you're likely to build your personal problems right into the machine itself."

     They just look at me, thinking about this.

     "It's an unconventional concept," I say, "but conventional reason bears it out. The material object of observation, the bicycle or rotisserie, can’t be right or wrong. Molecules are molecules. They don't have any ethical codes to follow except those people give them. The test of the machine is the satisfaction it gives you. There isn’t any other test. If the machine produces tranquillity it’s right. If it disturbs you it’s wrong until either the machine or your mind is changed. The test of the machine’s always your own mind. There isn't any other test."

     DeWeese asks, "What if the machine is wrong and I feel peaceful about it?"

     Laughter.

     I reply, "That's self-contradictory. If you really don't care you aren't going to know it’s wrong. The thought’ll never occur to you. The act of pronouncing it wrong's a form of caring."

     I add, "What’s more common is that you feel unpeaceful even if it’s right, and I think that’s the actual case here. In this case, if you're worried, it isn't right. That means it isn’t checked out thoroughly enough. In any industrial situation a machine that isn't checked out is a ‘down’ machine and can't be used even though it may work perfectly. Your worry about the rotisserie is the same thing. You haven’t completed the ultimate requirement of achieving peace of mind, because you feel these instructions were too complicated and you may not have understood them correctly."

     DeWeese asks, "Well, how would you change them so I would get this peace of mind?"

     "That would require a lot more study than I’ve just given them now. The whole thing goes very deep. These rotisserie instructions begin and end exclusively with the machine. But the kind of approach I’m thinking about doesn’t cut it off so narrowly. What’s really angering about instructions of this sort is that they imply there’s only one way to put this rotisserie together...their way. And that presumption wipes out all the creativity. Actually there are hundreds of ways to put the rotisserie together and when they make you follow just one way without showing you the overall problem the instructions become hard to follow in such a way as not to make mistakes. You lose feeling for the work. And not only that, it’s very unlikely that they’ve told you the best way."

     "But they’re from the factory," John says.

     "I’m from the factory too," I say "and I know how instructions like this are put together. You go out on the assembly line with a tape recorder and the foreman sends you to talk to the guy he needs least, the biggest goof-off he’s got, and whatever he tells you...that’s the instructions. The next guy might have told you something completely different and probably better, but he’s too busy." They all look surprised. "I might have known," DeWeese says.

     "It's the format," I say. "No writer can buck it. Technology presumes there’s just one right way to do things and there never is. And when you presume there's just one right way to do things, of course the instructions begin and end exclusively with the rotisserie. But if you have to choose among an infinite number of ways to put it together then the relation of the machine to you, and the relation of the machine and you to the rest of the world, has to be considered, because the selection from many choices, the art of the work is just as dependent upon your own mind and spirit as it is upon the material of the machine. That’s why you need the peace of mind."

     "Actually this idea isn’t so strange," I continue. "Sometime look at a novice workman or a bad workman and compare his expression with that of a craftsman whose work you know is excellent and you’ll see the difference. The craftsman isn’t ever following a single line of instruction. He’s making decisions as he goes along. For that reason he’ll be absorbed and attentive to what he’s doing even though he doesn’t deliberately contrive this. His motions and the machine are in a kind of harmony. He isn't following any set of written instructions because the nature of the material at hand determines his thoughts and motions, which simultaneously change the nature of the material at hand. The material and his thoughts are changing together in a progression of changes until his mind’s at rest at the same time the material’s right."

     "Sounds like art," the instructor says.

     "Well, it is art," I say. "This divorce of art from technology is completely unnatural. It’s just that it’s gone on so long you have to be an archeologist to find out where the two separated. Rotisserie assembly is actually a long-lost branch of sculpture, so divorced from its roots by centuries of intellectual wrong turns that just to associate the two sounds ludicrous."

     They're not sure whether I’m kidding or not.

     "You mean," DeWeese asks, "that when I was putting this rotisserie together I was actually sculpting it?"

     "Sure."

     He goes over this in his mind, smiling more and more. "I wish I'd known that," he says. Laughter follows.

     Chris says he doesn't understand what I'm saying. "That's all right, Chris,” lack Bareness says. "We don’t either." More laughter.

     "I think I’ll just stay with ordinary sculpture," the sculptor says.

     "I think I’ll just stick to painting," DeWeese says.

     "I think I’ll just stick to drumming," John says.

     Chris asks, "What are you going to stick to?"

     "Mah guns, boy, mah guns," I tell him. "That’s the Code of the West."

     They all laugh hard at this, and my speechifying seems forgiven. When you’ve got a Chautauqua in your head, it’s extremely hard not to inflict it on innocent people.

     If you recognize the book, congratulations on having a fine memory. If not, it’s Robert M. Pirsig’s Zen and the Art of Motorcycle Maintenance: An Inquiry Into Values. It has a fair claim to being one of the most influential books of the Twentieth Century.

     Pirsig’s style is much like mine: He orbits his central point until he can arrow in on it with decisive force. In the above, the central point is the importance of an esthetic of elegance – an artist’s esthetic – to the writing of a technical document. And he nails it.

     The dismissive attitude so many tech vendors have toward the documentation of their wares is a symptom of an important sickness. That sickness doesn’t yet have a name. It tolerates ugliness and awkwardness where elegance and simplicity should reign. The emphasis is on saving a few pennies on the development budget when saving the eventual customer’s sanity and good will ought to be the highest priority. It’s a great part of the reason for experiences like the one I narrated yesterday.

     Elegance and simplicity are the twin progeny of a profound understanding: a comprehension of the wherefores of the device and its design, in whole and in part. If you don’t understand the design of the device and the principles behind it, you’ll never produce an elegant, simple set of assembly instructions. If you don’t understand the reasons the customer would purchase the device, you’ll never write an elegant, simple User’s Guide: i.e., a document good for something other than a doorstop.

     Food for thought for your Monday.

5 comments:

pc-not said...

That was very informative, Fran. I have found that YouTube has partially solved this problem whereas an ordinary Joe sixpack can do a "show and tell". They are not all correct or well made, but I usually hit the jackpot with one or two people giving a succinct demonstration.

JWM said...

If you want to see an absolute masterpiece of technical writing, buy one of Bandai's Perfect Grade Gundam models. You know what a Gundam is, right? It's one of those three story tall battle robots- well, not actually a robot. It has a human pilot cocooned in a tiny cockpit in the chest. The Zeta Gundam was top of the line when I bought it many years ago. The attention to detail is nothing short of amazing. The kit builds a fully transforming figure just over 12" high. It has close to a thousand pieces if you include wires, screws, and LED's. The instructions are all in Japanese. At first glance you look at the long, long book, and just say, "No way..." On more careful study you realize that the instructions are remarkably clear. It does take some patience, but even with no knowledge whatever of the Kanji, the assembly is easy. Yes, it does take great peace of mind to slow down and study the process before beginning. But it works. One caution, however. The kits are as addictive as crack cocaine. "I'll just build the left leg engines this afternoon..." 3:00 am, the wife is asking why you're not in bed, and you're telling yourself, "I'll stop as soon as I get the arms done."

JWM

Mark said...

I am reminded of an episode of M*A*S*H where an unexploded bomb has landed in the middle of the 4077th's compound. Hawkeye and Trapper are attempting to disarm the bomb, while Henry and the others read the appropriate instructions to them from a safe distance. All is going smoothly until:

Henry (via megaphone): The next step is to cut the blue wire...

Hawkeye snips the blue wire

Henry: But first....



WalkingHorse said...

Nicely done! Good documentation has as its prerequisite a knowledge of both the intended (and some unintended) uses of the product/device/process in question in situ, an understanding of how it behaves internally at at least the block diagram level, and how the 'user interface' interacts with those internal components. As should be obvious, needlessly complex systems frustrate the achievement of those levels of understanding.

These issues go to the heart of why few of the major systems we depend upon are worthy of much confidence. It is expensive and time consuming to address the functional, non-functional requirements of a system, the means by which the system may be adapted to address flaws or future capabilities, how users are to interact with the system. Quality documentation is hellishly difficult and expensive, and it is almost the first thing sacrificed when the suits start pressuring the development team for something to demonstrate.

It is reminiscent of Thomas Jefferson's apology, which goes something like, "I apologize for writing you such a long letter. If I had taken more time, I could have been more succinct."

Manu said...

I do need to read that book.

I never have, and many have recommended it to me.