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

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!

Tweet, don't twitter

"Talk rapidly and at length in a trivial way * " is what prompted this blog post. I've been on Twitter for close to two years now and thought it was time I compiled a "Thou shalt not" list for tweeting. So, here goes:

1. Do not use "Pls RT". Not only does that use up six characters, it also presumes I am not smart enough to know if something is good enough to be shouted of from rooftops.  That, and the fact I hate being told what to do.
2. Do not use up all 140 characters unless unavoidable. Leave enough room for your twitter handle (if someone wants to RT) and some comments (from people who're sharing your tweet).  The first is self-promotion, the second is courtesy.
3. Do not tweet ONLY to share your blog post URLs. Thanks, but we have feed readers for that.
4. Do not keep retweeting like there's no tomorrow. If we are linked through Twitter, there's a 1 in 2 probablity that our Followed list is very similar. Retweets by you clog up my timeline.  If you find yourself retweeting stuff too often, consider putting those tweets into paper.li and sending out ONE single paper.li-automated tweet daily. Besides, if all that you do is retweet, I am going to Unfollow you within a week (unless what I was looking for was a human feed-aggregator. For free).
5. Do not just retweet - tell me why you thought it was retweetable (see #2).
6. Do not be a radio commentator on the sports field. If I am as enthusiastic about that game as you, I am watching it (and not reading your tweets). If I hate sports, you're clogging up my timeline and, No, I can't filter you out because you never use hashtags and words consistently. This holds true not only of sports but of TV programs as well.
7. Do not tweet something that wouldn't make sense to 50% of your followers. What, you do not know about your followers? Bleh! You talking to chairs and tables, then - where's the point?
8. Do not tweet long updates one after the other, 16 tweets to a minute for 3 full minutes. If you have lots to say, use Twitlonger (or whatever) or write a blog post.

As with life, so with Twitter - do not blabber and do know who you are talking to.

--------
* One of the definitions of 'twitter (verb)' given by the Oxford dictionary

Disclaimer: Sorry for the rant post but I just had to. Rant, i.e.

Listen! Do you want to know a secret?

Let's start at the very beginning
A very good place to start
When you read, you begin with A-B-C

• A is for Adobe.  The company that left Anindita with the distinct impression that it thinks that that the techcomm world revolves around it. Also see F and R.
• B is for Beta.  It stands neither for the second letter in the Greek alphabet nor the second brightest star in a constellation. It stands for not-yet-ready releases and is an excellent medium for techcommers to get feedback on their work.
• C is for content. That which makes the techcomm world go round.
• D is for DITA.  That thing which cures all ills.  Sane voices suggest otherwise but people still see through the glass darkly.
• E is for English.  A language much maligned by a tiny, pint-sized apostrophe, which, if misaligned, can even become a comma. E is for editors. That group of people who are haplessly left with correcting the thats and whichs when what they’d dearly like to do is spend time on indexes, navigation, and coherence and cohesion.
• F is for FrameMaker (See A). F is for feedback. A message where the message is often confused with the messenger, often unjustly.
• G is for Google.  It is a help authoring tool that saves a lot of SME time (see S).
• H is for Help. A verb and a noun (See the possibility related V). Help is a privilege. You may want it but not get it.
• I is for information. Information is a noun that cannot stand on its own; it must always be used as an adjective. Information design, information architecture, information developer, and information overload, for instance.
• J is for coffee and pictures. As in, Java and JPEG.
• K is for knowledge.  Of, besides writing, the tools, domains, and processes.
• L is for listening.  It stands for the characteristic of being alert and ready to hear anything that might lead to knowledge (see K).
• M is for multimedia, an umbrella term for anything that moves, creates noise, and can be packaged.
• N is for No. As in, “No, I will not document how it should work; only, how it does indeed work”, “No, I will not put this screenshot here because …”, “No, this will not go into an install guide because….”
• O is for obfuscation.  So long as obfuscation exists, so will a technical communicator.  If you do not know what obfuscation is, here is an example: “The relationship, which I might tentatively venture to aver has not been without a degree of reciprocal utility and even perhaps occasional gratification, is approaching the point of irreversible bifurcation and, to put it briefly, is in the propinquity of its ultimate regrettable termination.”
• P is for PDF.  It was born in 1993. Other births that year include Microsoft Windows NT and the republics of Slovakia and Czech.
• Q is for  curiosity. Why should I…? How does this…? When will it…? If I do this, what will….? What’s the difference between…? What is the weight of the moon?
• R is for RoboHelp (See A). R is for respect. An emotion that causes much existential angst among techcommers.
• S is for scrum. It means giving daily updates to your team and then running back to do the work you yourself promised to. S is for SME.  It means the fount of knowledge from which information must be gleaned. S is for substance (See C). S is for style. It is something best only followed, not tampered with.
• T is for Twitter.  A medium used almost exclusively to pimp blog posts, product launches, and rave reviews. T is for TWIN. Bonded for life.
• U is a letter so important that it must never be used in isolation. U is royalty and must always be teamed with other letters, like this: UX, UA. U is the reason techcommers exist; U is for users.
• V is for vision. That which makes techcommers put descriptions in alt text, pick the reds and greens with care, and prefer lists to tables. The ability to see beyond the obvious, to ‘write’ for everyone.
• W is for wiki.  Everybody knows it’s there but nobody knows what to do with it, hoping that somebody comes up with a wiki-to-source roundtripping that helps anybody adopt a wiki.
• X is a placeholder. As in XML.
• Y.  A letter for which I could not come up with a word. I did try to match it to words such as Yes, Year, Yearn, and Yesterday but felt something was missing.  So, I am leaving Y alone. For You, the reader.
• Z is for zen.  And the art of writing for motorcycle mechanics.

When you know the notes to sing
You can sing most anything

====================================================

This first appeared in the Nov-Dec2010 issue of INDUS, STC-India's newsletter.

Acknowledgements

• Rachna Singh Ganguli for G = Google, F = feedback, Help is a privilege, J=Java and JPEG, R = respect; T=TWIN.
• Anagha Bhat-Chandratrey for K = knowledge, L = learning.
• The Beatles, for “Listen! Do you want to know a secret”.
• The people of The Sound of Music (1965) for “Let’s start…with A-B-C” and “When you know…most anything”.
• The people of Yes, Minister (BBC) for “The relationship…termination”.

Woo hoo! Smart search is possible

Watson had not been on my mind when I wrote my last blog post. In fact, if you were to shake me awake in the middle of the night and say, "Watson!", my immediate response would have been "Elementary, Holmes!" Despite being vaguely aware of a project called Watson underway in my company, the name didn't really mean "Wow" to me till, well, last night.  But before I tell you why, let me go back a bit - and talk about my last blog post. In that post, I had implied 'storage' and 'retrieval' are two different things and, while tagging and indexing might work when one is storing something, the same tag or index could fail while retrieving the data. In my post, I had put foward a question - should content be context insensitive for it to be reused effectively? Conventional wisdom - that which runs search engines and SEO jobs - says, "No".

And then came along Watson, and beat two people in Jeopardy to win an indecent amount of money, which, it was declared, would be given to charity.  A computer beat two awesome humans.

Somewhere halfway through this video, when analysing why Watson got 'Chicago' wrong, you'll see the IBM engineer say something like "the info was stored in sectors but this was not about discrete compartments" or something to that effect.

Exactly! Human brain does not process information in linear paths. It hops, skips, jumps, runs around in circles. And, because we're getting there - with Watson's help - I think in my lifetime at least I'll see content being reused in ways that I (the writer) never imagined it could be because the user (with help from Watson) is retrieving just that much - and only that much - information that the user needs. Correctly, every time, the first time.  Smart user!

Lose that tag please

It all started last night when I tweeted some Hindi film dialogues (In India, we have two major religions - films and cricket).

(to zoom, click the image)

And then, we got around to discussing the bestest comedy film that's ever come out of Bombay. And, this was the tweet that got me to writing this blog post.

(to zoom, click the image)

How is this relevant to techwriting?

Well, if I were an indexer, I'd have probably tagged all my film content with some of these words: bombay, bollywood, hindifilm, <nameOFfilm>, <nameOFstar>, and so on? Very search friendly and all. But say, my reader was a sociologist researching corruption in India (ahem!).  This dialogue ("Thoda khao, thoda phenko" #epic) would never even show up in the search results, yet it contains exactly what the sociologist is looking for - the entire social mileu from which the phenomenon has sprung (including the defence mechanisms people employ to forget the misery it produces).

So, how did I link this dialogue to scams (that are occupying the entire front page - and more - of newspapers these past weeks)? Because in my mind, my content database is neither indexed nor tagged. I can pull out random references and tag it to anything random and yet make it look relevant.

Me: To copy, perchance to paste; Aye, there's the rub for in that paste what copies might come when we have shuffled the platforms and the versions out of the filters.
Colleague: Coils. Not filters. Coils.
Me: Coils.
<silence for one minute>

Colleague: A coil is a wrapper, right?
Me: Right.
Colleague: So, if we put a wrapper to call the boolean....

So, here I am, thinking if there is more to indexing that meets the eye. More to content reuse? More to "context"? Thoughts?

Where is the User in the Design

Creation and delivery of help content was what was on my mind as I sat crocheting a tiny coin purse for my mother.  She has a very cute, 3-inch, pot-bellied leather purse that she uses to keep her loose change in but it's coming apart at the seams, hence I sat there, crocheting this:

To zoom in, click on the picture

And, have we not often come across something like this:

To zoom in, click on the picture 

[Note: Thanks for catching the misplaced apostrophe. Feeling too lazy to edit the pic.]

I am picturing a scenario with me and my mom:

 To zoom in, click on the picture

Creating and delivering help content is very similar to creating any other product.  So, I ask myself, Where, How, and When is my reader going to need this information.  If I can answer these three questions, the content I create will truly be User Assistance.