"It is difficult getting a bunch of hyperactive seven-year-olds to concentrate on geography. I asked them to name five Indian states and most of them stopped with Delhi, Haryana and U.P.", lamented my aunt. I looked up from the newspaper. She'd been handling the unenviable task of "introducing" the "social sciences" at one of the lower classes in her school, and today had evidently been a bad day.
"The problem with this city is that..", said uncle-the-elder (handlebar moustache, backbrushed hair, stern glare) "…it understands only money. No history, no geography, and absolutely no civics."
I bit back a rude reply as I realised that my falling-asleep-over-the-newspaper plans would be delayed by a culture-vs-money diatribe from uncle-the-elder. So I took a deep breath (it calms the temper) and, looking straight at my aunt (who was now gulping water straight from the fridge – "bad for her throat", I thought immediately), I declared in the most solemn tones that I could muster, "Take the social sciences out of their books and bring it into their lives. If they understand only money, throw a few notes in their faces and they'll learn more about India in a day than you can ever imagine. To teach them geography, show them the colour of money."
For a minute, there was silence - the kind where people try to figure out whether they really heard what they thought they heard. And then uncle-the-younger (has immense faith in my sanity, god bless him) said with exaggerated politeness, "Would you please care to elaborate?"
Whereupon I leaned over and extracted the wallet from aunt's purse (a pot-bellied contraption from Khan Market that carries everything from safety-pins to petro-cards), drew out a 100-rupee note, waved it and asked, "What do you see?" And pre-empting anybody, I continued "The first thing that you see is Gandhi. Which state is he from? Gujarat. Look at the bottom left corner. Do you see the three lions? They are from a pillar near a stupa at Sanchi, in Madhya Pradesh." I flipped the note. "See the one-hundred-rupees written in 15 different languages? Which states speak these languages?"
By now I had a captive audience.
"This gets curiouser and curiouser", said uncle-the-younger. "Do I also see the Himalayas?"
It was, however, still difficult to convince uncle-the elder. "So, they now get to know the states. That’s all."
"Nah," I said. "You get the history too. Who was this guy Ashok who built the pillar at Sanchi? Why did he build it? When did he?"
Little cousin picked up the cue (she's all of 23, and even streaks her hair, but I still think of her as "little"). "And then, there are these interesting bits about the elephant and the tiger that are unique to the country (she'd drawn out a 10-rupee note from the wallet). And Ma look, what is this lighthouse thing on the 20-rupee note?"
"I'll get the class to find out", said the aunt.
I looked at uncle-the-elder.
"Hmmph, so what you're saying is that to speak to someone I should know their language?"
"Exactly", I beamed. "Else, they won't understand you."
-------------------------------------------------------
Lesson learnt: Analyse your audience.
-------------------------------------------------------
Wednesday, July 9, 2008
Tuesday, June 10, 2008
The Expert and I
It’s a few days into your new job, you’ve just wandered back to your seat with your coffee, and your team-lead says, "There’s this product that’s gonna have a version 3 release some time next month. Two new features have been added. Can you update the online help?"
Ho-hum. There’s already some sort of a Help, and all you need to write about are the two new features. That should not be difficult. But wait, consider the following scenario:
* The design document, also referred to by some people as the SRS (Software Requirements Specifications), has not been updated ever since version 1 was still on the drawing table.
* Version 2 was released about two years ago. The person who documented version 2 has since left the company. No one knows where the legacy doc files, and related reference stuff, are - all they have is a chm file that ships with the product.
* The software is for an industrial automation system. You know nothing about industrial automation.
You ask, "Um, I need some inputs. Whom can I ask?"
"Oh, we are all there to help you", grand sweep of the arm indicating the entire doc team. "Besides, for your product, there’s this SME whom you can ask if you need anything."
"Of course, the SME", you think, "the subject matter expert. That’s a good place to start looking for info."
But wait, no. Don’t plunge headlong into interviewing an SME. First, prepare yourself. How? The following list gives some pointers.
1. Do your research. Go through all the legacy docs that you can lay your hands upon, and jot down the points that you do not understand. get your hands on the “old” executable files, install them locally and run yourself through the software (or, if this is not possible, ask for a time-share on a machine that has the software running). Once you have a list of questions, look for answers on the net. There’s Google, there’s wikipedia, and there are mailing lists. But, when writing to a mailing list, please be specific. Who has the time to respond to messages with "Need help urgently" in the subject field and "Hi! I am new to technical writing. I have been given the task of updating the documentation of a legacy product. How do I go about it?" in the message body? The experienced people on a mailing list don’t have the time to spoon-feed people who cannot research. Do a focussed reading, read up as much as you can, and write down specific questions. For example, "The software that I am documenting has a graphical interface that lets engineers manage the pressure in a boiler system. I am looking for inputs in……" Time yourself - to guard against the tendency of getting lost in links within links - and focus.
2. Ask your doc-team members. They’ll be more than willing to help you get started (and remember to pass on the good turn when you are "old" and there’s someone "new" around).
3. Prepare a list of questions. You would have had a list at step 1 itself, but you’ve researched the stuff and you’ve asked your team-mates, so, with that knowledge, pare down the questions.
4. Find out where the SME sits, walk over to that cubicle, introduce yourself, and set up a meeting. Tell the SME why you want the meeting, and how long you think the meeting would take. SMEs are busy people, like all of us, and will appreciate the fact that you know they’re busy and that you’re asking only for an X amount of time. More often than not, they’ll readily give a time.
So, you have now read up on the product and the domain, gone through the legacy docs, have a fair idea of what you want to know, and have set up a meeting with a person who’ll supposedly answer all your queries. It’s interview time now. How do you go about it? The following have worked for me:
1. Listen. Some of us have this tendency of showing the SME how much we’ve learnt about the product. Please spare the SME’s time (and yours), and listen with both your ears. Keep jotting down notes, and if you do not follow something that the SME said, there’s no harm in saying, "Can you please repeat that? I need to write it down." Which brings me to the next point.
2. Ask questions. Please do not get bogged down by thoughts such as, "I hope that’s not a dumb question." All questions are dumb. Don’t believe me? Think of the very dumb question - Why did the apple fall down? Asking questions leads us to discovering new things. All questions are potentially wise. Ask, therefore, like a student, like a user, of the SME, who is the expert. Ask as an expert should be asked by a novice - humbly - and make the SME see that you’re genuinely interested in the answers. Think, like a user of the product would, and ask.
3. Understand the product. Figure out why you, as a user, should use this product (and not some other). An SME doubles up as a product evangelist (mainly because the SME’s the one who actually created the product) and will love to answer your questions on this point. Learn about the usability of its features, why one should use a particular feature, when one should and should not use a particular feature, and so on. Ask the SME about test cases and use cases, and listen closely. Let the SME see that you are doubling up as the user of the product, and lead the SME to talk about those things that may not have been documented anywhere. ("This is a known issue, but we’re not looking at it now because there’s a workaround, we’re concentrating on enhancing Feature A, …."). It may be just one feature that you’re documenting (and they’re enhancing) but it’s important to get that feature right.
By this time, you should be pretty much armed. You’ll start documenting the deliverable assigned to you. It may so happen that you’ve followed all the above steps so effectively that you do not need to go back to the SME again. But wait. Remember, the SME gave you a lot of time, and a piece of that hard-disk otherwise known as the SME brain? It’s time to return the favour. Consider doing all or any of the following:
1. Follow-up the face-time with an email that says thank-you and asks did-I-miss-anything? Chances are that you do not get a reply (which may mean that you didn't miss anything). Chances are that if everything was covered, the SME will mail back saying no-problem (that’s an Indianism, but I am not discussing Indianisms here). Chances are that if you did indeed miss out anything, and the SME's being helpful, you'll get a mail with some more info. In any case, you have taken the first step towards building a rapport that goes beyond the immediate need - that of the current project. You and the SME may get thrown together again.
2. Communicate the pain points you encountered when you were siting there running through, unasked, the test cases and use cases. Keep your communication polite and matter-of-fact. It may just be that you’ve discovered a usability issue that the SMEs (experts that they are) failed to spot. The SME may even walk over to your cubicle and thank you because you spotted a bug that would’ve otherwise got logged as a defect and got reflected in the metrics.
3. Keep in touch after the project is over. Don't believe people when they say: An expert is one who knows more and more about less and less till they know absolutely everything about nothing. SMEs don't bite,and you’ll be amazed at the fun you can have just sharing the lunch.
--------------------------
P.S. This post assumes that SMEs and writers work physically at the same office. What if they don’t? That subject’s for a future blog post. :-)
--------------------------
Ho-hum. There’s already some sort of a Help, and all you need to write about are the two new features. That should not be difficult. But wait, consider the following scenario:
* The design document, also referred to by some people as the SRS (Software Requirements Specifications), has not been updated ever since version 1 was still on the drawing table.
* Version 2 was released about two years ago. The person who documented version 2 has since left the company. No one knows where the legacy doc files, and related reference stuff, are - all they have is a chm file that ships with the product.
* The software is for an industrial automation system. You know nothing about industrial automation.
You ask, "Um, I need some inputs. Whom can I ask?"
"Oh, we are all there to help you", grand sweep of the arm indicating the entire doc team. "Besides, for your product, there’s this SME whom you can ask if you need anything."
"Of course, the SME", you think, "the subject matter expert. That’s a good place to start looking for info."
But wait, no. Don’t plunge headlong into interviewing an SME. First, prepare yourself. How? The following list gives some pointers.
1. Do your research. Go through all the legacy docs that you can lay your hands upon, and jot down the points that you do not understand. get your hands on the “old” executable files, install them locally and run yourself through the software (or, if this is not possible, ask for a time-share on a machine that has the software running). Once you have a list of questions, look for answers on the net. There’s Google, there’s wikipedia, and there are mailing lists. But, when writing to a mailing list, please be specific. Who has the time to respond to messages with "Need help urgently" in the subject field and "Hi! I am new to technical writing. I have been given the task of updating the documentation of a legacy product. How do I go about it?" in the message body? The experienced people on a mailing list don’t have the time to spoon-feed people who cannot research. Do a focussed reading, read up as much as you can, and write down specific questions. For example, "The software that I am documenting has a graphical interface that lets engineers manage the pressure in a boiler system. I am looking for inputs in……" Time yourself - to guard against the tendency of getting lost in links within links - and focus.
2. Ask your doc-team members. They’ll be more than willing to help you get started (and remember to pass on the good turn when you are "old" and there’s someone "new" around).
3. Prepare a list of questions. You would have had a list at step 1 itself, but you’ve researched the stuff and you’ve asked your team-mates, so, with that knowledge, pare down the questions.
4. Find out where the SME sits, walk over to that cubicle, introduce yourself, and set up a meeting. Tell the SME why you want the meeting, and how long you think the meeting would take. SMEs are busy people, like all of us, and will appreciate the fact that you know they’re busy and that you’re asking only for an X amount of time. More often than not, they’ll readily give a time.
So, you have now read up on the product and the domain, gone through the legacy docs, have a fair idea of what you want to know, and have set up a meeting with a person who’ll supposedly answer all your queries. It’s interview time now. How do you go about it? The following have worked for me:
1. Listen. Some of us have this tendency of showing the SME how much we’ve learnt about the product. Please spare the SME’s time (and yours), and listen with both your ears. Keep jotting down notes, and if you do not follow something that the SME said, there’s no harm in saying, "Can you please repeat that? I need to write it down." Which brings me to the next point.
2. Ask questions. Please do not get bogged down by thoughts such as, "I hope that’s not a dumb question." All questions are dumb. Don’t believe me? Think of the very dumb question - Why did the apple fall down? Asking questions leads us to discovering new things. All questions are potentially wise. Ask, therefore, like a student, like a user, of the SME, who is the expert. Ask as an expert should be asked by a novice - humbly - and make the SME see that you’re genuinely interested in the answers. Think, like a user of the product would, and ask.
3. Understand the product. Figure out why you, as a user, should use this product (and not some other). An SME doubles up as a product evangelist (mainly because the SME’s the one who actually created the product) and will love to answer your questions on this point. Learn about the usability of its features, why one should use a particular feature, when one should and should not use a particular feature, and so on. Ask the SME about test cases and use cases, and listen closely. Let the SME see that you are doubling up as the user of the product, and lead the SME to talk about those things that may not have been documented anywhere. ("This is a known issue, but we’re not looking at it now because there’s a workaround, we’re concentrating on enhancing Feature A, …."). It may be just one feature that you’re documenting (and they’re enhancing) but it’s important to get that feature right.
By this time, you should be pretty much armed. You’ll start documenting the deliverable assigned to you. It may so happen that you’ve followed all the above steps so effectively that you do not need to go back to the SME again. But wait. Remember, the SME gave you a lot of time, and a piece of that hard-disk otherwise known as the SME brain? It’s time to return the favour. Consider doing all or any of the following:
1. Follow-up the face-time with an email that says thank-you and asks did-I-miss-anything? Chances are that you do not get a reply (which may mean that you didn't miss anything). Chances are that if everything was covered, the SME will mail back saying no-problem (that’s an Indianism, but I am not discussing Indianisms here). Chances are that if you did indeed miss out anything, and the SME's being helpful, you'll get a mail with some more info. In any case, you have taken the first step towards building a rapport that goes beyond the immediate need - that of the current project. You and the SME may get thrown together again.
2. Communicate the pain points you encountered when you were siting there running through, unasked, the test cases and use cases. Keep your communication polite and matter-of-fact. It may just be that you’ve discovered a usability issue that the SMEs (experts that they are) failed to spot. The SME may even walk over to your cubicle and thank you because you spotted a bug that would’ve otherwise got logged as a defect and got reflected in the metrics.
3. Keep in touch after the project is over. Don't believe people when they say: An expert is one who knows more and more about less and less till they know absolutely everything about nothing. SMEs don't bite,and you’ll be amazed at the fun you can have just sharing the lunch.
--------------------------
P.S. This post assumes that SMEs and writers work physically at the same office. What if they don’t? That subject’s for a future blog post. :-)
--------------------------
Subscribe to:
Posts (Atom)