Show Don't Tell - The Language of the Story and the RFP

Show don't tell. It is THE quintessential writing advice for good reason. Don't tell us that a character is brave - show them facing a fear. While you're at it, don't tell us they are afraid - show us the quickening pulse, the sweaty palms, the tightness in the belly. Paint a word picture. Avoid "telling" words  such as nice, beautiful, good. Those words don't tell us anything.

I know; I'd promised a technology post, and here I am prattling on about standard, entry-level writing tips. That's because as a consultant someof my biggest contributions are written. Specifications. Narratives. System descriptions. All the details that go into creating an RFP.  While technical writing is in many ways different than creative writing, this one piece of advice holds strongly for both: show, don't tell.

There's a temptation to write a specification in such a way as to make the user feel that they're getting something special - expecially in the more specialty spaces on a larger job. I've seen language such as this:

The auditorium will be served by left and right program speakers, for high-quality stereo audio...

or

Flat-panel displays for high-resolution video playback of multimedia content.

or

Paging speakers for highly intelligible voice reproduction.

Compare those with

 The basement is dark and scary

Absent a definition of "high-quality audio", "High resolution video" or "highly intelligible voice reproduction" there's no objective goal. From a purely functional perspective, those words add nothing to either a contractor's understanding of the project or to the creation of a standard of success. Absent a description of the "scary" basement, you're literally giving the reader nothing but a dark space.

Two things can go wrong with such vague language. First, a contractor looking to cut corners or maximize profit can provide equipment with insufficient capability for the intended use. This can devolve into a fight in which the definition of "high quality" or "high resolution" is disputed. At the very worst, you can get a situation in which a contractor is either unwilling or unable - because their understanding of "high quality" is different than yours - to deliver a solution which is satisfactory to the client.

The other goal accomplished by more precise use of language is the setting of a finish line. There has to be some way for everyone to agree that a project is done. If an end result is described with purely subjective language, one is dependent on the client's subjective impression to agree that a project is successfully complete. Did you write "high-quality audio" in official bid documents? Good job - now you have a client standing in the room saying "it doesn't sound very high quality to me", and you have no way to tell him anything different.

So how do you do it? You fill in the darkness by painting a word picture. The only difference is whether that picture belongs in an art gallery or a set construction documents.

Some things are easy. Paging systems should have an STI (speech transmission index) target. This is an objective measure to which a system can be designed for intelligibility. High quality audio? SPL level, frequency response (+/- n dB over a range of frequencies) and other such objective criteria can give an actual target and actual design parameters. It'll make things easier for everyone.

Furnish paging speakers per contract drawings. Paging system should reproduce sound at a level of 75dB SPL at a height of 4' above finished floor. This system should achieve an STI of no less than 0.65

There are secret parts of the basement where nobody goes. Behind the boiler. Under the oil tank where winedark stains smell of old engines.  In the cracked parts of the foundation where tree trunk-thick waste pipes snake off to the underground. ... A little nook under the workbench, smelling of sawdust and oil layered over damp, earthy secrets. Sometimes, if I lay very quiet, I could hear their whispering. Low, languid, earthynoises, deeper even than my father's bellow but so soft and gentle.

Perhaps not the best descriptive text I've ever written, but it's paints a far better picture than "The basement is dark". So far as the paging spec is concerned, the improvement is clear; we show (using a number or objective measure) rather than tell (using a subjective statement of "quality"). At system close-out, it makes the difference between "the STI level is measured at .45, which does not meet standards" to "it doesn't sound good to me." The problem with the latter is clear: I've seen contractors chasing an elusive "It doesn't sound good to me" far, far too long into what should be simple projects. 

Issues with vague language can linger, and get into a user's head.  

If I wrote:

     We walked into the woods

Do you see this:

     The lantern cast a little pool of light in which they saw only branches and brambles. Dried leaves crunched underfoot as we walked on. This was closer to the nightmare of being lost in the woods, but not too close. The familiar gravel path was nearby. It had to be.

Or this?

     Truth be told, it isn't much of a wood, but there are trees and moonlight here in suburbia, what would have been an enchanted forest populated with dragons, witches, highwaymen when I was a boy. They're nice, straight, tall pine trees, but not connected to the famous pine-barrens. Perhaps they were  some time in the distant past, but now it's just enough to inflate the property value just a bit, and
to keep us from seeing our back-fence neighbors.

It's the same with "good audio"; if you don't show the reader what you want them to see, they'll tell their own story. That might not be the story you wanted to tell, or the story that you wanted to tell. Once the readers have told their own stories in their heads it's very hard to regain control of the narrative.

Does this always work? Are there times when you can't use numbers? Absolutely. Is there room for simile and metaphor? Perhaps. That is another discussion for another day.

Thanks for listening.