Thursday, March 26, 2015

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.

Friday, March 13, 2015

Why the Sun Did Not Rise Today

This was going to be an audiovisual post, but sometimes there's an event about which I simply must write. Yesterday was such an event in the world of literature.

I'll start by saying that the death of a celebrity is not something which usually affects me on a personal level; I was sad, but didn't cry over Robin Williams. Same for Leonard Nimoy. I don't feel close enough to them for it to have a visceral impact. That said, I cried when I saw this on Twitter:










For those who've not read Terry Pratchett (and if you've not you should have), Death is a recurring character in his Discworld series of fantasy books. His dialog is always in all capitals, so this final series of tweets on the occasion of Sir Terry's passing reads as a meeting between the author and his creation as the Reaper takes  his hand and leads him to whatever lies beyond. Yes, I cried over it.

I felt that we already mourned him once when he learned he had a rare form of early-onset alzheimers, but with the books continuing to appear it seemed that he'd be with us always, and cheat death. We know that that isn't the case for anyone. We can, of course, take comfort in the work he left behind. In one sense he'll never truly have left us as long as his work is still to be read. What did we lose - especially those of us who would never meet Sir Terry? I'm reminded of a scene from Neil Gaiman's Sandman graphic novels. The personification of dreams (known as Dream) had just died. Cain and Abel (from the Bible. It's THAT kind of book. Also highly, highly recommended) were discussing the funeral with another character:
“Nobody died. how can you kill an idea? How can you kill the personification of an action?""Then what died? who are you mourning?""A point of view."
Isn't that all that ever dies? Someone's unique way of seeing the world? We still have the legacy of Sir Terry's words and ideas. What we don't have is anyone who sees the world exactly as he did.

Who Was Sir Terry?
Pratchett at a convention. You have to love his
self-deprecating sense of humor
He's best known as a humorous fantasy writer, his best known work by far being the Discworld series. I discussed the series overall in my review of what was, tragically, the very last volume in a post here. How sad it makes me feel to have given so poor a review to a master's very final work! The first time I read one of his books was over twenty years ago now, making his a presence through half of my life to date. He was extremely prolific and extremely engaging.

The primary tribute I've seen online has been to share favorite quotes. I'll do the same herein, starting with a bit on economic justice. Neil Gaiman, another terrific British writer, described his friend Pratchett as a very angry man, whose anger fueled a decades-long writing career. Here;s his character, police chief Sam Vimes, on income inequality

"Take boots, for example. He earned thirty-eight dollars a month, plus allowances. A really good pair of leather boots cost fifty dollars. But an affordable pair of boots, which were sort of OK for a season or two and then leaked like hell when the cardboard gave out, cost about ten dollars. Those were the kind of boots Vimes always bought, and wore until the soles were so thin that he could tell where he was in Ankh-Morpork on a foggy night by the feel of the cobbles. 
But the thing was that good boots lasted for years and years. A man who could afford fifty dollars had a pair of boots that'd still be keeping his feed dry in ten years' time, while a poor man who could only afford cheap boots would have spent a hundred dollars on boots in the same time and still have wet feet. 
This was the Captain Samuel Vimes "Boots" theory of socioeconomic unfairness. "
But the thing was that good boots lasted for years and years. A man who could afford fifty dollars had a pair of boots that'd still be keeping his feed dry in ten years' time, while a poor man who could only afford cheap boots would have spent a hundred dollars on boots in the same time and still have wet feet. This was the Captain Samuel Vimes "Boots" theory of socioeconomic unfairness. "


He was also a writer who is very easy to dismiss, as he primarily wrote not just fantasy but comic fantasy. In my eyes, fantasy is important in that it gives us another language to tell truths too big for literal language. In closing, I'll share the quote the activist and writer Steampunk Emma Goldman shared. The scene here is a scrap of dialog between the aforementioned Death and his daughter Susan. They've just saved The Hogfather (a sort of Santa-Claus analog in the Discworld universe) from assassination. Susan had been told that, had the Hogfather died, the sun would not rise the next day.


"Now...tell me..."
WHAT WOULD HAVE HAPPENED IF YOU HADN'T SAVED HIM?
"Yes! The sun would have risen just the same, yes?"
NO."Oh, come on. You can't expect me to believe that. It's an astronomical fact."THE SUN WOULD NOT HAVE RISEN.She turned on him."It's been a long night, Grandfather! I'm tired and I need a bath! I don't need silliness!"THE SUN WOULD NOT HAVE RISEN."Really? Then what would have happened, pray?A MERE BALL OF FLAMING GAS WOULD HAVE ILLUMINATED THE WORLD.They walked in silence for a moment."Ah," said Susan dully. "Trickery with words. I would have thought you'd have been more literal-minded than that."I AM NOTHING IF NOT LITERAL-MINDED. TRICKERY WITH WORDS IS WHERE HUMANS LIVE."All right," said Susan. "I'm not stupid. You're saying humans need...fantasies to make life bearable."REALLY? AS IF IT WAS SOME KIND OF PINK PILL? NO. HUMANS NEED FANTASY TO BE HUMAN. TO BE THE PLACE WHERE THE FALLING ANGEL MEETS THE RISING APE. "Tooth fairies? Hogfathers? Little-"YES. AS PRACTICE. YOU HAVE TO START OUT LEARNING TO BELIEVE THE LITTLE LIES."So we can believe the big ones?"YES. JUSTICE. MERCY. DUTY. THAT SORT OF THING...YOU NEED TO BELIEVE IN THINGS THAT AREN'T TRUE. HOW ELSE CAN THEY BECOME?"

Today many of us feel that the Hogfather has died and that, in place of a glorious sunrise, the clockwork of the world turned in such a way that we'd face a large, burning ball of gas.

Wednesday, March 4, 2015

Curt Schilling is Not the Victim - the limits of shame in the fight for public civility


First off, I apologize to any of my fans for being away from this space for so long. As you all know, these have been trying times for me and my family; My lovely wife Karine had major back surgery just over a month ago, and is now convalescing in our home on Long Island. It's been a very difficult road in terms of her immediate recovery and hospital stay (including a long stint in the ICU), continued post-surgical pain, and the challenges of caring for two young children with one parent out of commission. I'll thank all of you who have offered kind wishes and who have supported our ongoing fundraiser to help cover expenses (special thanks to Gary Kayye of Ravepubs, Tim Albright of AVNation, and Corey Moss et al of the cAValry Rides show for lending their respective platforms to help spread the word. Thank you, AV friends!). It seems thematically fitting that my return to blogging will touch on the theme of family. Worry not, there will be more to say about the world of AV, fiction, and other thoughts. I'll start, however, with recent events involving former pitcher turned semi-professional loudmouth Curt Schilling.


 
Say what you will about him - we'll never forget Schilling's
performance in the 2004 ALCS.
Image courtesy of CNBC
For those living under a rock, Schilling posted a simple message on Twitter congratulating his daughter for getting into her college of choice where she will pitch on the softball team. The reaction - as it too often is when a woman is involved anywhere on social media - turned misogynistic and nasty including rape threats, reference to very aggressive sex acts, and overall nastiness. Schilling responded on his blog with a rant about civility, about how people need to learn that their actions have consequences, and included the names of some of the worst offenders. Two were students who were promptly suspended for their conduct; one was - in a poetic twist - a ticketseller from Schilling's old rivals, the New York Yankees. They fired him, along with a statement that they have zero tolerance for such conduct.

At a glance, everything is as it should be; a man defended his family from verbal bullying, the bullies paid a price. Nobody innocent was hurt, and we were given an example as to why we need to treat people civilly. The global community shunned these miscreants as a local village would have in times of old. Yet part of me can't help but feel uncomfortable, for a number of reasons.

First and foremost is the emphasis on Curt Schilling. He's famous, his daughter Gabby is not.  Yes, he chose defend his family and to name and shame. What he has not done, as of this writing, is direct any of that attention to those bullying women NOT related to famous baseball players. In his blog post, he said the following:

I mentioned being a Republican, being a Red Sox and all that other stuff. I didn’t insert politics to make a point, I did so to make sure if you read it you knew that I KNEW people hate me for one or more reasons.

[snip]

I look at it like this. If someone walked into your house and punched your daughter square in the face, what would your reaction be? You and I probably are thinking the very same thing. How is that different than what happened to my amazing Daughter?



This, to me, can be read as framing the bullying as a crime against him, Curt Schilling rather than against his daughter Gabby. At best, it puts the focus on him. At worst, this and the mention of Gabby's boyfriend paint bullying of a young woman not as a crime against her, but as a property crime against the men in her life to whom she belongs. Was this Curt's intent? That I can't answer, but even if we give him the benefit of the doubt it's hard to not see that as a message. In the meantime independent computer game developer Zoe Quinn continues to receive rape and death threats, Anita Sarkeesian is forced to cancel a speaking engagement due to death threats, Brianna Wu faces literally two years of harassment and threats from a man who later claims that it was some kind of elaborate performance art (and no, I'm not making that up. I wish I were). What makes the latter cases different? Wu and Sarkeesian and Quinn don't have powerful men to speak on their behalf; All they have are their own voices against the small, pitiful, but loud "GamerGate" movement dedicated to attacking outspoken women under the guise of "ethics in video game journalism". Their own voices aren't enough to have us listen.

That brings the bigger problem; there is no systemic way to deal with things like this. "Name and shame"  favours the loudest voices, those who already have power. Gabby Schilling's harassers were punished not because of what they said, but because of who their victim's family was. Schilling is not only famous and wealthy, he's a loud, polarizing figure who knows how to get our attention. A similar attack on, say, my family would get zero public attention. I'm one hundred percent in favor of platforms such as Twitter allowing anonymity; there are many legitimate activists and members of marginalized groups who depend on it. That said, they need to take a more active role in stopping this kind of behavior. I'm not such a free speech fetishist that I'll accept harassment as the price of doing business.

Even those of us who dislike Curt Schilling will fight for his daughter. We feel as if we know him and, by extension, her. Sure, he's the crazy uncle with reprehensible political views and a shaky grasp - at best - of science. That doesn't make him any less OUR crazy uncle with reprehensible ideas.
 

Finally, there's the issue that absent legal remedies we've resorted to the extralegal weapon of shaming. This is open to all kinds of abuse, both intentional and subconscious. Consider the following thought questions:
  1. Is it likely that the same swift response would meet a victim of color?
  2. Is the response equal across the board, or is it arbitrary?
  3. One harasser lost a fairly low-paying entry-level job. Should a repercussion to such things be an inability to work? If so, how is he expected to feed himself?
  4. One harasser was suspended from college. Is an inability to get an education a reasonable repercussion? How will this benefit society?
  5. How does your response to Item 4 blesh with the fact that prisons often offer educational programs to inmates? Could this be seen as worse than a prison sentence, for either the harassers or for society?

I won't lie, I'm a primate just like you are (I assume all of my readers are primates. Apologies to any uplifted dolphins reading this on waterproof smartphones). My first reaction was satisfaction that justice was done; someone did something bad, and we hurt them. Stepping far enough back, I don't see this as a solution. I see one very powerful man throwing around his muscle against some nobodies without moving to take any steps to solve the bigger issues. I see the community reading about this brushing its collective hands together, muttering to itself "good job" while higher levels of more persistent harassment continue. I see an emotional response, not a logical one. Judicial approaches have a fixed penalty, standards of proof, and - at best - a path to post-penalty rehabilitation and reintroduction to society. This kind of ad hoc shaming has none of that. Can we do better? I want to believe that we can.

As always, thanks for listening. I'll be back soon with something on the world of audiovisual technology.