Techwriting lessons from films

This post contains what I presented at the STC India annual conference of 2011 at Chennai.

---

We'll go straight to the first of the film clips. [The videos might take a while to appear on the page. Depends upon the internet speed.]

When chess pieces go missing

The lesson I learnt from this movie sequence?  That I need to be more concerned about my core skill (writing) than the tools I am using to practice that skill.  That, as a writer, my other core skills must be agility, resourcefulness, and adaptibility so that I can work with whatever is available to deliver that which is deadlined.

On to the next lesson.

You have to ask me nicely 

As a writer, I am on cross-functional team meetings, I test software, I file defects, I coax people to share their knowledge…I need to  know the people I am talking to. And, I need to ask them nicely. Because, I work with talking-feeling humans for:

• Getting information from the development teams
• Getting the technical and editorial reviews done
• Getting feedback from customer-facing teams
• Getting support from the doc team

Next clip.

Are my eyes really brown? 

My takeaway from that question was Accuracy - My writing must be free from mistakes, must adhere to facts.  I must:

• Write only that information which you have understood and verified
• Maintain consistency of all information about a subject

On to my next lesson.

I'll speak real slow

This one is about Clarity, about freedom from ambiguity or obfuscation, about presenting the information in such a manner that it can be understood the first time

Here, let me show you a film sequence that demonstrates what is not Clarity.

I'll speak real slow 

Now, I'll show you a scene from a Sunny Deol movie.

Dropping down dead

Some docs are so heavy, trying to read them is like being hit by a ton of bricks.  Docs that knock me down dead.  The lesson I learnt from Sunny's killer punch is about Retrievability and Organisation.  About how my documents must:

• Provide helpful entry points
• Facilitate navigation and search
• Give an index
• Provide you-are-here indicators
• Suggest links to similar or related information

Next on to my all-time favourite Kamal Hassan movie.  No, I don't understand Tamil, the language that this movie is in but hey! this clip doesn't need me to know Tamil.

What language was that

This one's about Style, about the correctness of writing conventions, and of words and phrases.  What I learnt from this film sequence is that I must always:

• Use correct grammar, spelling, and punctuation
• Follow template designs
• Use boilerplate text
• Follow style guidelines

Here's the next clip.

When you have to shoot, shoot

My lesson? Task orientation. I must focus on helping getting a job done.  I must classify my information by its type so that I can:

• Create docs in a consistent manner, so that the right design gets used (for example, tables for reference information, step sequences for tasks)
• Focus on tasks, and move the supporting concepts and reference information into other topics, where they can be read if required and ignored if not

When my information is focussed on the task at hand, stripped of all supporting information, here's how I can help people get their jobs done.

When you have to shoot, shoot 

And now to the last of the film clips.

Broken bones 

This one's about Visual effectiveness, about how I should:

• Ensure that all users can access the information
• Use graphics to complement the text

---

Acknowledgements

• Films: Shatranj Ke Khiladi, A Few Good Men, Casablanca, Deja Vu, Fandango, Damini, Salangai Oli, The Good The Bad The Ugly, Beverly Hills Cop, and Rear Window
• Books: The IBM Press book called Developing Quality Technical Education