Tuesday, February 24, 2009

The Personable Manual

Why do product manuals sound formal and stiff-upper-lipped? Why don’t users read manuals? These questions have haunted the hallowed precincts of Technical Writing for quite some time now. From what I have seen in Indian writers, I am forced to conclude that English Composition, as we were taught in school, is the culprit. Our merit was based on how verbose we were. They judged our style based on how ‘formal’ we were.

Take for example, the leave letter. I am sure you have written a few in school or college. Rewind and replay one of those leave letters. Right from the salutation (‘Respected sir/madam’) to the signature (‘Faithfully/Obediently yours’) it reeks of colonialism. And, we have yet to learn our lessons. In this age of globalization (or globalisation, to my stiff-upper-lip comrades), it is important to pay attention to the three Cs: Consistency, Context, and Culture.

The You
I have read manuals that say ‘you can perform this task…’ and in the next chapter add, ‘Users should back up data regularly’. Who is the ‘you’ and who is the ‘user’? Quite a few of my esteemed friends that are Technical Writers shy away from using ‘you’ in their manuals. Again, it is that skeleton in our cupboards (or closets, if you will, my American friend) called Colonial Composition that proves to be the stumbling block. I do not wish to debate on the aesthetic merit of using (or not using) ‘you’ in our manuals. The goal of your manual is to help users be productive. So let us stick to that story for now.

Let us look at an example:
1) If the system displays a blue screen, the OS should re-installed.
2) If your system displays a blue screen, re-install the OS.

Let us not discuss active and passive voice. Let us focus on the word ‘your’ that replaces ‘the’. Both statements offer the same instruction. If you took a poll with your users on which one they liked. I am quite sure they’d pick the one with ‘your’. Why? Because it is personable. The statement is talking to the user and thus telling the user ‘there’s something in it for you’ and urges action. There is no ambiguity (‘OS should be installed? By who?’). And, the ‘your’ statement costs less to Localize.

Also, it is important that your product offers a favorable emotional experience to your users. That is where the Colonial Composition fails. Ask any Interaction Designer and she’ll tell you how important Subjective Satisfaction is to the success of any design.

Personable Manual
Personable writing pays. What would you prefer to read?
"It is recommended that you upgrade your software."
"We recommend that you upgrade your software."
The latter engages you. It makes a convincing statement. It doesn’t hide behind the facade of passive voice, and it puts an arm around you and requests, like a friend, to do the needful.

There again, some of you might say ‘well, if we screw up, then because we used ‘we’ we may get into a soup.

Let me reassure you here: 1) you don’t write for a contingency called screw-up. 2) You write to ensure your user increases her productivity. And 3) Whether you write in passive voice or active voice, if it is in the manual, you are liable.

Finally, being formal is overrated. Just because you are in business does not meant you have to be business-like in your manual. That is a sad misconception. You got to connect. You have to converse with your user. You need to engage and offer a positive emotional experience to your user. Else, the user will pick that phone and call Support. Now, that, in my book, completely obviates the need for publishing a manual. And, having a writer on board.

Write to me: Sumank[at]gmail[dot]com

Friday, November 21, 2008

Promoting Document Usage: Taking a leaf out of Business Directories

You can argue all day that you know a customer that reads your manuals but my point is that most don't. It is a blessing in disguise for most of us: we get away with some really sloppy writing. But if you honestly want to help your customers but don't want to incur support costs, here goes:

Don't talk to them about your cream. Talk about beautiful, flawless skin. Didn't get it? No problem. Most software vendors bundle documentation or at least provide documentation online. And, most think their duty ends there. It doesn't. If it did, explain why customers still call up your Support Desk for information; the same information that your manual offers.

The explanation to this predicament lies else where: Business Directories. I used to be a Sales Rep for Tata Press Yellow Pages in Chennai (they call it InfoMedia now). After publishing and distributing the directory to users (all homes with a phone), they ran a publicity campaign. The campaign was meant to educate users on how Yellow Pages can help them. "Looking for an Architect? Look under Architects category in Tata Press Yellow Pages" Or something like that. The success of the brand depended on people using the product.

Do you promote the usage of your product documentation? I know the answer. Most of you don't. So what should you do?

Talk to your marketing/sales and support folks and send periodic e-mails to your customers. "Did you know that the Deployment Guide can help you customize the interface?" Or "Want to integrate MS-Office with your_product_name_here? See the Office Integration chapter in the Deployment Guide."

1) Track the kind of support calls you've been receiving
2)Identify common issues
3) Address them in your documentation
4) Highlight the fixes in your usage mail campaign
5) Start from step 1 and keep iterating!

I said track support calls instead of 'take a survey' because I don't believe in surveys. Surveys are the equivalent of you asking your dinner guests 'Hope you liked the food!' The answer is always yes, unless you have a socially aberrant guest who'd say 'Yuk. That food sucks!'

Think about it.

Write to me: Sumank[at]gmail[dot]com

Monday, September 01, 2008

Comics and Technical Communication

As always Google breaks away and uses a comic strip to do a launch-promo for its - hold your breath - web browser! Ladies and gentlemen, say hello to Chrome.

Maybe, just maybe, comics can be used for Quick Start Guides? Place Mats?

Write to me: Sumank[at]gmail[dot]com

Thursday, May 08, 2008

Tech Writing Manager? So What?

One of the 'tech writing managers' wrote on the TWIN list about this 'exclusive' Google Group he'd created for 'tech writing' managers. Here's what I wrote in response:

One of my very good friends runs a small software product company in Chennai. When I walked into his new office for the first time, I was stunned: plush interiors, air-conditioning, and a 'CEO' cabin! I was impressed.

I visited him again after a few months and noticed that he was sitting 'with' the team. The cabin was empty and I found a huge couch in the place of the Teak wood table.
The girl next to him was watching a movie. The guy next to him was chatting on G Talk. And our CEO stood up and ushered me into the 'cabin'. I asked him 'you don't sit here any more?' He smiled and said, 'I realized that if I sat 'with' them they'd feel I am 'one of them' and that's key to the success of an R&D environment.' I couldn't agree more.

I asked him, 'What's with that couch?' My friend's smile stretched till his ears as he said, 'When one of us are tired or spaced out, you know? We go and take a nap in that former CEO cabin.'

Bravo! I am sure you'll hear about him and his company very soon. There's no way this company can NOT succeed! Anyway...

I am just curious:

How are management issues different in technical writing? Management is management, right? You hire and manage people. You supervise project execution. Um, oh! you motivate people. You take the team to the next level. whatever that means? What else? Every manager, be it managing a snack bar in Domlur or a NASA lab, does that.

Don't you think you are flouting a key management principle by announcing your exclusivity to the green (and not so green?) world? I meant 'Work with them not 'on or away from them'

I could be wrong in assuming a whole bunch of things. Don't get me wrong! However, I'd appreciate a few responses: from ladies, gentlemen, and managers of the TWIN list. :-D

Come now, sense of humor is required for a manager. Especially tech writing managers.

Your thoughts?

Write to me: Sumank[at]gmail[dot]com

Friday, May 02, 2008

Use it before you write it.

From the Nikkor ED 80-400mm f/4.5-5.6D VR Review (emphasis is mine):
[quote]Here's the warning in the manual: "When the camera is pointed down, be careful not to hold the lens at the very end as indicated by the black marks in Fig. F, because the zoom ring or focus ring may rotate and pinch your fingers."

Huh? The camera doesn't have to be pointed down for this to happen, so I don't know what Nikon's crack manual writers were on when they wrote that. Worse still, your fingers will often be in that position because this is a heavy lens and you're likely to be trying to balance it by holding it near the front. The first time the camera racks focus on the lens from near focus to infinity at 80mm and your fingers are in the way, you'll get a rude shock as you think your fingers are about to be crushed by the receding front elements (at longer focal lengths, the front elements are further out and pinching is not likely). Fortunately, there's a small ramp on the bezel that tends to push your fingers out of the way, but it's still possible to get seriously pinched, especially if you have fat fingers.[/quote]

OUCH! Very rarely they read what we write and we get caught. So an embarrassed me quickly glances around, ensures no one's watching, and gets off the bus.

Write to me: Sumank[at]gmail[dot]com

Thursday, April 24, 2008

The Zoho CRM User Manual

I admire and respect Zoho a lot. These guys walk their talk on usability. These guys adopted blogging and wikis with a vengeance and I am sure it is paying off.

So, when the cat called curiosity bit me, I downloaded their PDF manual. And, I am sad when I say this, I screamed in my head 'you too Zoho!?' I could see actual content only after 14 pages. That my friend is a sin. And, the bookmarks do not appear on the left-pane. It is bad enough that you offer PDF manuals: you don't zip them; refuse to tell me the size of the file or how long it'd take to download IN TO MY GODDAMNED BROWSER without my permission! Why can't people just zip the PDF! PDF is for print. Not for online consumption.

No, don't say 'everybody does it!' That is not the point. When you as a company set out, embraced, and made usability central to your product(s), why the hell would you treat your user manual like you would a homeless bum?

That said, Zoho's wiki-based documentation seems cool. But PDF... WHY!? gaawd! Why? For a Saas product that too!

Write to me: Sumank[at]gmail[dot]com

Tuesday, October 30, 2007

My STC India Annual Conference 2007 Slides

Contingency design does not figure much in conversations amongst technical communicators. In these conversations, the emphasis is usually on the almighty manual. However, oftentimes, customers read error messages before they even think of opening a product's manual. In this presentation, Suman Kumar introduces the key area of contingency design and answers questions like 'How do we design for contingencies?', 'Can you use error messages to boost customer experience and loyalty?', and 'How does effective contingency design help in reducing support costs?'

Find out:
Contingency%20Design.zip (2.28 MB)

Write to me: Sumank[at]gmail[dot]com

Tuesday, August 21, 2007

I will be talking at the STC Annual Conference in Goa

Contingency design does not figure much in conversations amongst technical communicators. In these conversations, the emphasis is usually on the almighty manual. However, oftentimes, customers read error messages before they even think of opening a product's manual. In this presentation, Suman Kumar introduces the key area of contingency design and answers questions like 'How do we design for contingencies?', 'Can you use error messages to boost customer experience and loyalty?', and 'How does effective contingency design help in reducing support costs?'
Read more on the STC Website.

Another interesting paper is by Rachna and Shilpa of Cadence: Test plans as a source of improving documentation quality.


Write to me: Sumank[at]gmail[dot]com

Wednesday, August 01, 2007

Citibank Online Banking: Bad Example

There's a service called RTGS in Citibank. If you have a Suvidha account and you use the online facility, chances are, you must have seen it on your screen. Now, here's an example that borders on stupidity. The Citibank website says:
RTGS transfers allowed only for amounts between Rs 1,00,000 to Rs 2,00,000
Please do not include spaces or characters. For example, Rs.7,800.00 should be entered as 7800.00

Did you say 'So, what's wrong with that example?' Hmm?

Write to me: Sumank[at]gmail[dot]com

Saturday, June 23, 2007

How often...

...have you clicked OK without reading the message?

Write to me: Sumank[at]gmail[dot]com