by Mark L. Levinson

Examples love to be misunderstood.  I think it has to do with their religion.  An example is written to mean one thing, but if someone thinks that it means something else instead, then the example believes it has merited an additional soul.

If on an e-mail list you phrase a question in terms of an example, someone will always answer regarding a tangential point instead of the point you intended.  You ask, “Is it okay to say ‘tomatoes are’ my favorite vegetable, or must I say that ‘the tomato is’ my favorite vegetable?”  Someone is bound to answer, “It doesn’t matter, because a tomato is actually a fruit.”

You try to write the example so that it reaches out a well-directed hand to the reader, and the reader grabs the example by the tail. 

When you’re describing a product or procedure, there are a few especially sinuous tails — opportunities for misunderstanding — to watch for in any lengthy example.

An example normally starts by describing a specific situation (or assumes that the reader understands the situation), and then it tells how the general principles manifest themselves in that situation.  Suppose that you want to select a wide necktie.  You call your necktie collection to the display screen.  You see no wide ties because the narrow ties are grouped at the start of the collection.  You can click the arrows at the bottom of the screen to see more neckties.

Wait a minute.  Are the narrow ties always grouped at the start of the collection?  Is that a general statement describing how the product works?  Or is it merely part of a hypothetical situation concocted for the sake of the example?

Be careful to distinguish clearly between what is always true and what is specific to the setup of your illustrational story.  Also, be careful to distinguish between the setup and the payoff.  For example, suppose you log in to the TiePlumb necktie straightness gauge program and the lighting is poor.  You receive the message, “Can’t identify necktie.  One of these?” and three roughly similar neckties from the database are shown on screen.  If you answer “No,” you go automatically to New Necktie Registration.

The reader can’t say for sure how much of that story belongs to the “suppose” proposition and how much is the consequence.  The reader is being asked to suppose that the lighting is poor, but will the software always present three neckties?  Or is the reader being asked to suppose three neckties whereas the program might present two or four or seven if they were all sufficiently similar?

Lastly, every long example ends with an opportunity for misunderstanding.  The reader may think that whatever follows the example is still part of the example.  Back in Greece, Euclid and Archimedes would signal the end their mathematical proofs by writing hoper edei deixai, which has come down to us as the Latin abbreviation Q.E.D.  Unfortunately, nobody thought of a similar abbreviation for the end of an example.  I suggest ENOAD (example now over and done) to tie up the tail of the example.

Until ENOAD catches on, there are a number of solutions.  Sometimes a long example can be visually subdivided into discrete sections for premise and outcome, by means of columns or subheadings.  Or there might be a typographical convention whereby the outcome is, for example, italicized.  If such a solution is overkill, then the best thing to do is to reread all your own examples carefully, don’t shrink from repeating “Suppose... and suppose... and suppose further,” and use an expression like “when that happens” or “that being the case” to show the reader explicitly when you have stopped establishing the hypothetical and started narrating the inevitable.

Comments and questions are welcome: