Establishing Context, or Putting first things first

In a recent article that I wrote for Visual Studio Magazine (my first cover article for a journal that I didn't edit!) I made a claim that was immediately challenged by one of my on-line readers. I was right (of course) but so was the reader--it's just that I was right for the scenario that I was discussing and the reader was right for a different scenario.

In my technical writing course I always stress that the format for a section is "When, Information Critical to the Reader, Additional Stuff". That first part (the When) establishes when the information applies: It establishes the context for any subsequent information. In a side bar to my article I had made "claim A" and then later added "in scenario A." My reader pointed out that my statement was complete rubbish but was thinking about a different scenario (and, to be honest, the reader was considering the scenario that the main article focused on).

Had I followed by own advice and began the sidebar with "In scenario A, claim A is true" I could have avoided misleading my reader. This is the usual problem that technical writers have when dealing with material they're personally familiar with (I'm a programmer in another life). I call it the anthropic failure: "I know what I meant therefore my readers should also."

Oh, well and I'll try to do a better job next time.

You can read the article (and the exchange) here.

Reading or read:

• The Authentic Gospel of Jesus by Geza Vermes
• Selected Translations: Poems by Ted Hughes and Daniel Weissbort