Steven Pinker can get away with ranting about bad writing, but it remains to be seen whether I can. But since my rant more or less illustrates Pinker’s on a smaller canvas, possibly I may be indulged.
And I can only do so with a qualification: this particular aspect of bad writing is inherent—perhaps even inevitable—in one of the most difficult genres known to writers: explaining how to do something to someone who comes to the lesson relatively or even completely ignorant of the topic.
I’ve run into this aspect of bad writing a lot recently because I’ve been teaching myself new stuff. Like GIMP. Like Python. It’s the particular Python experience I now rant about. And I do so, believe it or not, with sympathy for the challenges faced by anyone who dares explain virtually anything involving a computer.
The book cost $35.00. It has lots of sweet little cartoons. But its writer lacks that single magic ingredient of good writing. He can’t imagine his readers’ minds.
Now, no one can ever completely enter and know another’s mind. If we could, we’d be each other. It’s the growing knowledge of difference that makes the existence of an “I” possible. (I didn’t make this up. I got it, in roundabout ways, from Emmanual Levinas.) But like it or not, writing for others, writing to be read, demands at some point some tangents of contact between the writer’s mind and the reader’s. Otherwise, we have gibberish. True, between some minds there never is such contact, and between those writers and readers there is gibberish. (I submit that the intersection, when it can be created, is where what is called “rhetoric” takes place.) But on to my rant.
Having downloaded and installed the program and having read in the introduction how welcoming a beginner like me would find Python, I proceeded to follow the directions for setting up the program on my Mac. Never mind that there were pages and pages of instructions for PC users and only a couple of paragraphs on Macs that instructed me to go back and read the pages on Linux. I eventually did find the screens that showed up in the figures, although the screen that came up when I dutifully clicked “Update Shell Profile” was supposed to “run” and as far as I could tell it just sat there, no matter what keys I plunked. At this point, I was already starting to seethe.
He kept telling me to “run” things in a “terminal.” He kept talking about “running” programs from the “command line.”
Well, I got the word “terminal” to show up in the menu line (still not sure how I managed it or whether I can do it again), so I assumed that the box that opened, with various references to my name and the date in plain text, was the “terminal.” But nowhere was there any apparent command I could click to “run” anything. And a “command line”? I looked in vain for the blinking cursor I remember from my short experience with Basic (and of course Wordstar) from 30 years ago. At the end of the text in the “terminal” was a little box that sat immobile no matter what I did.
I can hear you out there, your derisive mocking howls. But you’re the problem! You really do not want people like me to learn your secrets. You want to protect your arcane universe from the uninitiated (cf. Pinker).
But I foxed you.
After some forty-five minutes of reading and rereading the chapter, looking in vain for some definitions or some moment when he said, “In order to run a program, you do this and then this,” I conjured from somewhere some basic intuition born of those 30+ years of mud-wrestling with computers, often armed with nothing but my instincts and willingness to push buttons at random. I thought, I wonder if that little box is the “command” icon. What happens if I try to type there? And then, with the lines of the little demo program waiting, inert but there, I did what intuition sweetly whispered: I hit return.
Now I ask you, what would it have cost to tell me those two things?
Let me quote from the back cover: “Even if you’ve never written a line of code before, you’ll be writing real Python apps in just an hour or two.”
Another, very quick, related example: my first Adobe Connect session. No one conducting the session seems to have even considered the possibility that some in the audience had never been in that environment before. I missed the first twenty minutes of the presentation trying to figure out the basic layout, which proved to be accessible and useful with just the slightest bit of orientation.
There. I’ve said it. Done.
Except that this struggle to sense and foresee our readers’ needs is so fundamental to writing to be read that we ignore it at our peril. But why is ignoring it (or at least not recognizing it) so tempting, such a common phenomenon? I have a completely unprovable theory, which I’ll explain (with numbered steps) next time.