Wednesday, December 7, 2011

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.]

video

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.

video

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.

video

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.

video

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.

video

I'll speak real slow 

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

video

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.

video

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.

video

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.

video

When you have to shoot, shoot 

And now to the last of the film clips.

video

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

    Tuesday, March 22, 2011

    Recasting the recipe

    Just because I do something well does not necessarily mean I like doing it. Cooking, for example. Hence, I steer clear of all recipe booklets, cooking websites, and similar. But a weekend conversation on FaceBook about things planned for the Holi break needed me to sit down and write a recipe for my friend, fellow techwriter Samartha Vashishth. One look at my mail and he wrote back saying "put in blog post" etc. Hence.
    I know the first list in that recipe should've been an unordered one. :-)
    Let's take our edit hats off while we look at the recipe, shall we? 

    How is it different from standard recipes? Here's how:
    • It assumes you are doing only this task and nothing else. There's no "Do X and keep aside" instructions (despite possibilities); there's only a linear task flow.
      Lesson for techcomm: Do not introduce branches into a procedure.
    • It does not just list the ingredients but group them according to when they're going to be used in the process and what they're going to be used together with.
      Lesson for techcomm: Grouping of logically related items aids in (i) comprehension (ii) task completion.
    • It does not have pictures :)
      Lesson for techcomm: Use pictures only if they are essential to performing the task.
    How I could've made it better? Listed the utensils, perhaps. No recipe that I've come across ever lists them (except, maybe, cakes, and that too a grudging 5" baking tray mention) even though they are very important to the task at hand. Notice how, in step 9, I suddenly introduce a utensil (bharta toaster) that is otherwise not logically related to the cooking of haleem? Bad!