Dale's Tutorial Tutorial


– but only after steps 1 and 2 – by reading every sentence critically. Ask yourself "what have I said here that could be misinterpreted?" This has two parts: concept and phrasing.

If you read anything scholarly, such as an article in a scientific journal, you'll find the flow is often tortuous. At every step the author considers all the objections his peers will surely raise and attempts to forestall them before proceeding to the next point. When writing tutorial material, one similarly needs to consider every possible way the reader will find to go off on a wrong tangent when reading your words. We've all sat in a classroom listening to the lesson being interrupted by question after question from fellow students: "you mean such-and-such?" To which the teacher has to respond: "no: I meant so-and-so". When writing a tutorial your job is to anticipate every such mis-take on your meaning, since you won't be there to answer each reader's questions as they arise.

click for larger version

Minden rapids 5.

I've actually gotten compliments on this one...

At the conceptual level this is often a matter of trying to intercept your own unspoken presumptions. If you're writing a tutorial on apple farming and your experience is entirely with sweet varieties like the Macintosh, then everything you write assuming the goal is to maximize sugar content will be highly misleading to someone with a Granny Smith orchard ... and as I write that I wonder if my readers in Australia will even have heard of either of those apple varieties. So I would go back to add "(a sweet variety)" after Macintosh and "(a tart variety)" after Granny Smith, just in case. We can call this defensive exposition, in the same vein as defensive driving. ;)

At the phrasing level one checks that one's words say to other ears what they say to one's own ears. I write: "A tomato grower's first goal must always be to thin his plants." I read that to mean pruning unnecessary branchlets from each plant; you read that to mean pulling out plants that grow too closely to each other – a potentially costly misunderstanding!


– for typos, spelling mistakes, punctuation problems, and grammatical errors.

Some errors are actually misleading, but all errors erode your creds as a competent dispenser of knowledge. In my experience, the single most common source of error has arisen with the advent of the microcomputer: cut-and-paste mistakes. I start to write: "Here in Ontario the rain always seems to fall on those who don't carry umbrellas". I intend to change that to: "The rain in Ontario falls mainly on those who don't carry umbrellas". But end up with: "Here  the rain in Ontario falls mainly on those who don't carry umbrellas", because I cut the phrase "in Ontario", pasted it in the new location, then forgot to go back to delete the word "Here". The problem is that your eye expects to see what you believe you've written and so never sees the orphaned "Here" at the beginning of the sentence.

The obvious and best solution is to have someone with good language skills proof-read for you. Such people are hard to find ... and generally prove less willing to comply with each repeat request ... so you may as well polish your self-editing skills, you'll probably need them. Alternatively, brag to your spouse what a wonderful writer you are, then sit back, pretending to be hurt, as he/she points out problem after problem in your hard copy. If that's not an option, and you have the luxury of time, put your document aside for several days. With a good bit of luck you'll be able to read it with a fresh eye, hopefully catching some of those pesky hidden errors.

click for larger version

Fenelon Falls Lock 4

For all that I've encouraged you to start by recording your conversational flow, another source of problems are colloquialisms that are so familiar to the ear that they easily go unnoticed. You may try and solve this problem in your daily speech, but in the final draft of your writing you want to try to solve this problem. Few readers will consciously object to "try and"; but equally, few readers will fail to come away with a vague impression of amateurishness.

Similarly, in our daily speech we tend to leave out seemingly unnecessary or repetitive words and phrases. For example: this tutorial starts with: "Depressingly, I get compliments on my writing far more frequently than on my pictures." In conversation we all too often leave out that second "on". Another example: in my first draft of this section I wrote: "Double-check for typos, spelling mistakes, punctuation, and grammar." I didn't really intend to suggest that you check for the existence of punctuation and grammar in your writing; I'm sure most of us would have understood my intended "punctuation problems, and grammatical errors". Nevertheless, Mr Spock would have called me out on a logic error; and we don't want to argue with Mr Spock. Which leads me to my final gem of sheer sagacity:

Tip: Never write, but always proof, as though there are two people standing behind your back, reading over your shoulder. One is Mr Spock, checking your logic and your facts; the other is Miss Primly, your sternest, pickiest, least forgiving public school English teacher, critiquing your language.


Appendix: Persnicketies for the obsessive-compulsive

The above is what you really need to know. If you have been, or expect to be, writing more than very infrequently, you may want to read on: