Wishing my blog readers a happy 2009

I am writing this blogpost three days in advance because:

• I want to beat the Web jam likely to happen on 31st night (when "night" happens several times over, starting from Japan and travelling right across to the US of A).


• I want to ensure the post gets uploaded to cloudspace before Blogger decides to cap everything (because Blogger too may have a hangover).

I am writing this post to:

• wish you a very happy 2009.


• share my new-year resolution (I shall henceforth suffer all fools gladly provided they take no more than 10 minutes of my time), and ask you about yours.


• send across my new-year gift-box especially packed for you with the following items:
  
  
  
  • Some very special dangling modifiers, which were being given away free to anyone who purchased a copy of the book "I saw Janus peeking through the doorway".
  
  
  • A book called "Zen, and the Art of Agile Documentation", which is a special kind of book - to read the book you need to constantly run after it - that tells you how to generate Requirements out of Thin Air and create Online Help for Usage Scenarios.
  
  
  • A life-long chance to officiate as the Executioner of Capital Offense Committers, where you execute an "Off with the head!" command every time you come across a sentence such as "The Data Manager retrieves Queries and Historical Trends and presents them as Tables, Charts, and Graphs".
  
  
  • A sneak preview to my new book titled "My Life: In Bulleted Lists".
  
  
  
  

How to mechanise the harvesting

The process we followed for Phase 1 of the TWIN eBook was:

1. Copy-paste the useful stuff into a GoogleDoc file. Each category has a file.


2. In Robohelp, create an HTML file out of each question in a category, and in the navigation tree, bunch all questions of a category under their category.
   Saving the GoogleDoc files as Word files, and importing to Robohelp didn't work coz during the Googledoc > Word conversion, the formatting (and hence, the sequence of questions and answers) went for a toss.


3. Export Robohelp files as Word files, proofread.


4. In Robohelp, incorporate edits of stage 3.
   Which means, compare the text line-by-line.


5. Generate CHM.

To me, this seems unnecessary labour; stages 2 and 4 are especially wasteful. So, over the past several days, I've been thinking of changing the eBook process so that we can:

• eliminate the duplication of copy-paste at the compilation stage


• do on-going edits

I've come up with the following plan:

1. Use a database (simple row-column db) to store data. The db needs to let us:
   
   
   
   • Append through a Web-based form. Fields: category_main, category_sub, question, answer 1_name_email_date, answer 2_name_email_date, answer 3_name_email_date etc.
   
   
   • Search, based on fields
   
   
   • Define user levels: writer can put and get, editor can put, get and change.
   
   


2. For compiling, pull the data from the database and append XML tags. Each column is a tag.


3. Transform the XML to HTML, compile as CHM. The "category_main" and "category_sub" tags tell us the TOC.

Let's see how it goes. I'll need to research a bit.

Related post: Harvest, separate grain from chaff, release to market

Of crystal balls and a view

Last month, the STC India people made the following announcement:

We are pleased to announce a Writing Competition to coincide with STC India's 10th Annual Conference to be held in Pune.
Topic – Technical Communication in India: A Look into the Crystal Ball
Word Limit – 550 words
Style or Form – Open (essay, parable, fable, tale, poem…)
Format – Plain Text
Deadline – November 21, 2008

I can resist everything except a writing contest so I sent in my entry. It won a prize :-)

================= MY_ENTRY_BEGIN =================


Good evening, and welcome to Crystal Ball. Our guest today is Mercutio Hermes, who shares with us his view on Technical Communication in India. Welcome Mercutio.

Thank you. I notice you said "view", not "views". May I ask why?

Our show is about looking into the crystal ball. We share what we see there, and what we see is only a view.

So, you'll ask me questions, and I'll look into the crystal ball and respond with what I see?

Yes.

Great! Let's begin.

What do you see about technical communication in India?

I see a lot of writing.

What kind of writing?

Someone waving a bunch of APIs and yelling, "Robots can’t code; only humans can. It takes a human to decode a human".

What else do you see?

I see lots of rocket-science documents and aircraft-maintenance documents, and not all are in English.

They aren’t? What language are they in?

Oh, several languages, actually. Tamil, Urdu, Assamese, Dogri.

So, do you see translators becoming more important than writers?

Nope. I don’t see any translators at all. I see specialist technical writers writing in their native languages.

Interesting! Do look in again and tell us what else you see?

There’s a long line of teachers waiting to get themselves e-learning certified, and there’s a line of students - a line of which I see no end – waiting to get their hands on the latest tutorials and voicecasts.

You say you see podcasts in India? That’s interesting.

Yes, I see podcasts entering mobile phones and radio channels. The ones that go into the mobile phones also have annotated pictures to complement the voiceover.

You mean like the Google Chrome release notes?

No, not exactly. These are on-demand doc-support. Techwriters have fed their task modules into a NASSCOM-managed repository that is programmed to read the metadata embedded call-for-help-SMSes, fetch the matching task-module from the repo, and SMS it back to the mobile phone. Techwriters are writing e-modules that are have 10 sentences or fewer.

What else do you see?

I see a child writing an essay "When I grow up, I want to be a doctor. I will study neuroscience and design user interfaces."

What kind of user interfaces do you see?

I see these touch-screen interfaces, mostly not in English, that farmers are using to buy fertilisers and sell wheat. I also see box-like devices where villagers are swiping their bio-cards and doing their mobile banking; and even these interfaces are not in English. I see companies have inserted spy cameras into these devices. Whenever a user is stuck and calls up support, the techwriter who wrote the UI text is penalised.

Okay, so what you’re saying is the market for tech-writing services has gone domestic? It’s no longer international?

No, it’s not that Indian techwriters are no longer writing for international markets. But what I see in this ball is that many of them are writing solely for an Indian market for applications developed indigenously, and customised subsequently for the international market.

What about techwriters in non-Indian MNCs operating from India?

Well, what about them? I see them all there, writing DITA-based topics for Eclipse-based help systems, and predicting the death of Microsoft Word.

Thank you Mercutio. Your view has been interesting indeed.

Thank you for letting me see.

================= MY_ENTRY_END_550_WORDS =================

Harvest, separate grain from chaff, release to market

Once upon a time in India...

Mobile phones were unheard of, and internet at homes was only through the phone-line dial-up, which meant that every time you logged on to the web, the outside world could not call you up on your phone. The year was 1997 - when phone calls outside the city cost so much that there were slabs for off-peak calls, when the maximum download speed one could hope for was 256 kbps, when every minute of internet usage was charged so much that you logged in, copied your mails to the hard disk, logged out, composed the replies, and logged back in to email them. It was 1997 when personal computers were beginning to make an appearance in unlikely places (government offices, for example), people got their fingers stained changing the ribbons of dot matrix printers whose pin-distance could be adjusted just like a typewriter's...

...and "knowing computers" meant you knew strange languages that were called C, foxtrot, COBOL and Pascal. Did I say foxtrot? I meant fortran. Indian Railways used it to computerise its reservation system, and drew gasps.

This was the time when almost no one knew what technical writing was, and even among the few technical writers that existed in the country, almost no one knew the other. This was when someone thought of creating a mailing list. This person emailed to a few technical writers he knew, those in turn mailed to their friends, and thus the TWIN mailing list was born (years before Orkut popularised the friend-network concept). TWIN quickly grew in size and became a coffee house of sorts where people came to ask questions, leave replies, make announcements, post job ads, share knowledge...

It is 2008 today, and the TWIN mailing-list archive has over 35,000 posts. These posts represent the accumulated knowledge of a community sharing and learning from its members - a community exchanging notes about technical writing, tools of the trade, career, trends, best practices, and more.

However, searching the archives was not an easy task, and the accumulated wisdom was fast becoming inaccessible to all but very determined seekers. The TWIN book-compilation project seeks to make the info accessible.

The stated objectives of the project: weed out the not-so-useful, retain the useful, categorise the useful for quick access, and present the categorised info to the world.

I am talking about the project, bit by bit, on my WordPress blog.

Comparing Blogger.com and WordPress.com

After using for the past weeks the free blogging facilities offered by Blogger.com and WordPress.com, yesterday I sat down to list the similarities between them. Then, I jotted down the areas where each scores over the other. Finally, I created a wishlist. Read about it on my WordPress blog

If it’s not easy to use, it’s not used

Debates about Microsoft Word vs. Adobe Framemaker appear regularly on the tech-writing mailing lists I am subscribed to. Everyone agrees Frame is an awesome publishing tool. Yet, everyone keeps cribbing about it. So, why does a bright bunch of people who are masters at figuring out stuff, otherwise known as tech-writers, only hesitatingly agree Frame is “kind of great”?

Confession: I love Frame.

I think it’s mostly because Frame is so difficult to use. Its user interface is not intuitive (it doesn’t even have a print preview), and its Help sucks big time. Word, on the contrary, has a fantastic Help, and a user interface so easy even a child can use Word. Developers love Word - they can open Word files in any browser (or even WordViewer or Open Office), and they can review Word docs easily by putting in coloured lines of text (most I know never use the Track change or Comment features). Try turning a black word into red in Frame - and you need to go through a process!

“So what the heck”, thinks a bright techwriter. “If I can learn Frame, I might as well learn XML.” And thus is born a host of companies who get in place a documentation system that can handle big documents effortlessly (the single-most crib against Word) and can also offer single-sourcing (Frame’s big plus): their docs are written in XML by writers who need not worry about structure and formatting, which are taken care of by the XSL, DTD or FOSI that the consultant came in and wrote for a one-time fee. And their XML docs still get converted to HTML-like things that developers can open in their browsers and add their red-ink comments to.

And Word continues to sell - in the home segment as well as in the office (as a part of the Office Suite) - at rates and at volumes that keeps Microsoft happy and profitable. Frame, on the other hand, is so steeply priced that even companies think before buying it - and its steep learning curve doesn’t help.

If something is not easy to use, is anyone going to use it?

Blog's on Alltop

Last week, I got a mail from Guy Kawasaki telling me they'd put this blog up at their site Alltop. The blog's under the Technical Writing category.

:-) Wow, someone like Guy Kawasaki thinks this blog is interesting. In delight, I've put an Alltop badge in the sidebar of this blog.

 

User is king

I have an account with a public-sector bank. It's a bank that opened a branch right next to our new office (of one of my previous employer-companies), and it's where my salary was credited. I still have that account, but since it's about 7 kms from my residence, I was thinking in terms of internet banking...

"Not a chance", scoffed the brother. "It's a public sector bank; they're dinosaurs."

I didn't agree with that line of reasoning, so I went and checked their website. Sure enough, they had internet banking facility. They even had an FAQ for users of their internet-banking facility. I saw the FAQ page and saw red. The following image is a composite screenshot of their FAQ page peppered with my red-ink comments (to magnify the picture, click on the picture).



And then it struck me. I was looking at the Web page as a techwriter, not as a user.

An average internet-banking user of this bank would be an Indian whose primary language, either at school or at home, was not and is not English. Such a person would not even notice the errors I’ve marked. Such a person would find the text totally comprehensible, unambiguous, and useful - though a tad incomplete because it answers only about four questions and doesn’t even address the how-to of the options provided by the internet-banking facility.

Such a person is the average user of the webpage. Which means, almost none of my edits are required.

Does it matter at all that a minuscule percentage of users, like me, are put off by badly-written help? And no, it’s not because I am a tech-writer that I am put off. Ever since I can remember, I’ve hated badly-written text (even before I knew - courtesy technical writing - why I hated them). It somehow smacks of a cavalier attitude.

Coming back to the example in question - I, as that minuscule user percentage, am put off by the bank’s FAQ page and will never read it. How does that effect me, the user, and other users like me? I, for one, will never use their internet services, preferring to physically visit the bank for my transactions - if they can’t get their webpage right, they won’t get my online transactions right as well. Presumptuous and unfair of me, but still… Does it effect the bank? Nope. They’ve still got my account with them. But in the longer run, I may be leaning more towards banks that care…

So, where does audience analysis begin? And stop?

Matters of Ownership (ethics)

I've seen job ads where the recruiting companies want to look at samples of an applicant's work. I've heard technical writers declare brazenly, "Oh, I have removed all references to the company's name, and masked all the company-specific information. Therefore, I can use it as my sample because I have created it."

Please allow me to tell you a little story.

There's this old, wizened man back home in my native town. Let's call him Wajid Ali. He is the one who built the house that we live in. Why do we live in the house and not him? Because my grandfather owned the house and passed it on to my father. How could my grandfather own the house when Wajid Ali was the one to build it? Because my grandfather got the house built, Wajid Ali was only a contractor who was paid to build it. My grandfather had bought the services of Wajid Ali. At the end of the day, contractors do not own the houses they build.

Technical writers, generally speaking, are much like Wajid Ali. They are employed by others to write documents for those others. Despite all the hard work and creativity that goes into making those documents, at the end of the day it is those others who own the document, not the technical writer. It follows, therefore, that a technical writer cannot show off such documents without express permission from the document owners. The document owners have bought the document from the technical writers. This is what lies at the heart of all the stuff about NDAs and document ownership.

It is extremely bad behaviour (I am being polite, I swear) to use a company's resources (authoring tools, documentation infrastructure) to create something and show it off as a sample without seeking the company's permission first.

Oh, um, but we all may want to change jobs at some point of time. What do we do if we're asked to present some samples of our work? Two options come readily to my mind:

• Ask the document owner (present employer, contracting agency, whatever) for permission to use what I've created as samples.
  
• Create my own samples, in my own time, using my own resources.

:) Like I read in my very first book when I was a child of not even five years (yep, I started early) - পরের দ্রব্য় না বলিয়া ল‍ইলে তাহাকে চুরি বলা হয় | যাহারা চোর, তাহাদের কেও দেখিতে পারে না | (Translation from the Bengali original: Taking another's object without telling that person is called stealing. No one loves a thief.)

How to write badly

This blog post appeared in a slightly different form in TechCraft, an electronic periodical distributed free of cost to the members of the Yahoo group technical_writers_india. To subscribe to this group, send an email to technical_writers_india-subscribe@yahoogroups.com

---

In this blog post, I list some pointers that help you be a bad technical writer. Each of these instructions is followed by an example, and my thoughts on the example, but not a conclusion. This list is by no means exhaustive but I am limiting myself to the following nine because I can illustrate each one of them with real-life examples.

1. Practise anthropomorphism; empower the object

The YSQT database is a repository that:

• Has normalised data of more than one project, location of time period
• Lets you create trend graphs for more than one project
• Lets you create financial reports across more than one financial period
  

If the software has the power to let you do stuff, it is evidently an animate object. Really? Does the software let you do stuff, or have you (or another person) let the software let you do stuff?

2. Ignore the grammar; don’t write for a Nobel

The person in the picture begins with "This is Jane Doe", a sentence in the third person. Grammatically, a third person is a third party . But, there’s only one person in the picture. Where is this third party, this Jane Doe? The person in the picture goes on to say, "I will walk you through this…". So, what will Jane Doe do, and why was she introduced? Or, is "this" a demonstrative for both "Jane Doe" and "tutorial", and, therefore, refers to a tutorial called Jane Doe, and the lady in the picture is going to introduce Jane Doe, the tutorial, to us? I'm confused.

3. Ignore the dots and curls; let others figure out the punctuation

Click only once on all the go buttons. Once you click certain characters get added to your password just IGNORE.

Punctuation separates the elements of a sentence from each other and clarifies the meaning . The second sentence is wholly lacking in any such pointers and is open to multiple interpretations.

4. Use as few sentences as possible; make people read everything twice

In order to obtain the maximum benefit from the YSQT financial application, you need to have obtained the necessary license key as a paid user, which lets you gain access to the advanced features of the software, including the ability to send alerts to a specified cell phone number.

Is there a law against using short sentences? Is there a law that forces writers to lift stuff, verbatim, from the SRS document?

5. Introduce jarring notes; disturb the symphony

The properties of the YSQT word processor are listed below:

• Easy text entry, formatting, and editing
• You can import your WordPerfect, WordStar, or MacWrite files
• Check for grammar and spelling

When I see a sentence followed by bullets, I expect that sentence to flow into, and weave in and out of, the bullets. For me, things fall in place faster if they are synchronized.

6. Hop, skip, jump; introduce others to agile reading

To print the page on the shared printer, follow the steps given below.

1. Select File > Print > Page.
2. Ensure that you are logged in to the YSQT domain.
3. Ensure that the shared printer appears in the list of printers configured for your machine.
4. Click OK.

When they teach us to program, one of the first things they teach us is to draw flowcharts. Going back even further in time, before they teach us to spell words, they teach us the alphabets.

7. Ignore the style guide; add variety to life

Click Next to advance to the next page. To go to the first page, click First. Clicking Previous takes you to the page you viewed last. If you want to jump to the last page, click Last.

When I read a document, I expect it to conform to a pattern, and not fling something new at me at every step.

8. Show off your hard work; put a picture on every page

The pictures do not add anything to the text. They merely repeat what is stated, and take up space. By contrast, this Google Chrome documentation is a fine example of pictures speaking a thousand words.

9. Rely completely on the software spell-checker; don’t check for yourself

To get help on the filed, lick the help icon to the right of the field.

If you run an automated spell-check on this sentence, you'll get a clean report. Need I say more?

Of dots and curls - Comma blurb

There was this boy called Commah,
Who was so very prim and propah,
He'd never sit next,
To an uppercase text,
Unless it was a proper Nounah.

I want to be a technical writer

A couple of weeks ago, I met a friend from college. We met after almost 15 years, and did what such meetings usually end up in - reminiscing over coffee. Some time during the course of our conversation, the friend remarked,

My sister has decided to take up a full time career in technical writing. She is good in English and was a science student in her postgrad. What does she need to do?

The following paragraphs contain what I recollect of my answer to my friend's query.
=================================================================
She could probably start applying for jobs (Naukri, Monster etc. are good sites, and so are TW-dedicated sites such as TWIN). At this point of time, the "good" companies may not want to hire a fresher, but after a year's experience, changing jobs should not be a problem. Some of the prospective employers may ask for writing samples - your sister could consider writing any or some of the following:

• A How-to describing a small feature in some software she is familiar with; for example, How to create pivot tables in MS Excel. This serves as a sample for a user manual.
• A How-to describing the install procedure of some software that she's used; for example, How to download and install the OpenOffice suite. This serves as a sample for an install guide.
• A How-to describing the steps for doing something she may be doing regularly; for example, how to clean the spark plug of a motor cycle. This, again, could be a sample for a user manual.
  
• A white paper for a business scenario (for example, whether or not Company X should enter into the business of virtual worlds). This, besides being a sample white paper, doubles up as a sample for other marketing collateral that tech writers are sometimes asked to create. And also showcases skills such as the ability to research, sift out useful data, analyse them, and organise the stuff into a coherent argument.

Some prospective employers may ask for knowledge of "tools". I hate this question, but there's a world out there (at least in the circles I've moved in, which is India) that worships tools. I suggest that your sister make herself familiar with at least the following tools (they are freeware), and then say that she can learn other similar tools because she already knows the basics...

• Authoring tool: OpenOffice Writer (is similar to MS Word)
• Help compilation tool: MS HTML Help Workshop (is similar to Adobe's RoboHelp)
• Image editing tools: The PrtScr button on the keyboard plus MS Paint. MS Paint is not a freeware, but it comes bundled with the Windows OS...

This list still leaves out FrameMaker (about which interviewers will love to ask, just to scare you), but one can always say "I don't know". Alternatively, one can download a 30-day trial version of FrameMaker and play around a bit.
Some of the other things that one may be asked about in interviews are: structured authoring, DITA, XML. Your sister can read up on these things (Wikipedia is a good place to start).
Additionally, I found these to be useful:

• Wandering around at sourceforge.net, looking for "help wanted" for documentation, and volunteeriing. This is non-paid work but it showcases several things; such as your ability to interact with a remote developer, your ability to understand a piece of software as it develops and write about it, your interest in and commitment to the TW profession, etc.
• Reading Peter Grainge's site: http://www.grainge.org/
• Joining TW mailing lists such as the TWIN mailing list and TechWrl.

What is Technical Writing

In 20 words or fewer
Technical writing is creating documents that help someone install, deploy, configure or use a product or a service.

In 50 words or fewer
Technical writing is creating documents that help someone install, deploy, configure or use a product or a service. It results in the creation of things such as user manuals, admin guides, instruction booklets and help systems, but not of business proposals, white papers, case studies, and so on.

In 100 words or fewer
Technical writing is creating documents that help someone install, deploy, configure or use a product or a service. It results in the creation of things such as user manuals, admin guides, instruction booklets and help systems, but not of business proposals, white papers, case studies, and so on. However, the distinction between technical writing deliverables and general business deliverables is getting increasingly blurred. These days, technical writers are also called upon to create or edit marketing collaterals, press releases, internal training tutorials, computer-based training material, and so on.

The Covering Letter

I had already been working for more than 10 years when, in 2006, I switched to the technical writing field. The first job was fairly easy to find - I looked up the vacancies, found a few that I liked the look of, got a call for an interview, and got onboarded It was a fun, learning experience at that company. Two years later, I thought it was time for me to change jobs. That shouldn’t be too difficult, I told myself, since I am now “experienced”. Two months later, I realised that though I was getting responses to my applications, they were not really from companies that I was dying to work for. The “hey-I’d-love-this-job” vacancies that I had applied to weren’t generating responses. I gave a long and hard look at my résumé (though this blog post is not about that). I also gave a long and hard look at my covering letter. My English teacher in school had taught me that all non-letters (CVs, forms, cheques and drafts, etc.) MUST be accompanied by a covering letter, so my standard practice thus far had been something on the lines of:

So, I re-read this letter critically. “Yew”, I told myself. “Hiring managers of “hot companies” must be getting tons of these. What can I do to make my covering letter interesting enough to make them click that link that takes them to my actual résumé?”

I thought awhile and came up with a different covering letter. This is what I want to share with all of you in this blog post of mine. The covering letter that I finally sent out got me three interview calls within the space of an hour, and all of them from three “good” companies. I am at one of them today . This is what my edited covering letter looked like.

It may be a totally unconventional manner of doing things but I realise that it made me stand out from the crowd and still get taken seriously.

Money Matters (spot all nouns)

This blog post appeared in a slightly different form in TechCraft, a once-in-two-months e-zine distributed to the members of the yahoo group technical_writers_india. To subscribe to this group, send an email to technical_writers_india-subscribe@yahoogroups.com

---

Money matters.
What does the phrase mean? Does it refer to the matters related to money (money, n.; matters, n)? Or does it mean that having some money really does matter (money, n.; matter, vb)? Is matter a noun or a verb?
Phrases such as these are potentially confusing, not only to readers in English but also to translators who translate such disjointed, disconnected phrases that appear in the user-assistance deliverables that we as techwriters create. In today's globalised economy, where the bigger of the multinational companies earn a significant portion of their revenue from outside their home country, we need to be careful about what we document. Why? Because, in all likelihood, what we document is going to be translated into 10 different languages, if not more. When we write in English, if we could keep the following points in mind, it makes life a lot simpler for translators. Trust me :) I used to handle localisation projects (before I decided that I'd rather write the very source that gets localised).

(1) Write short sentences

Writing short sentences is the equivalent of speaking slowly. A sentence that is long-winded has to be read more than once to be understood. A translator works under deadlines, and re-reading stuff takes away that much of the translator's time. Consider the following sentence:

The YST server ensures that all hosting servers of a YST product or service always sync with each other with respect to product versions of the services hosted by them.

Phew!

(2) Do not use compound nouns that have more than two words

Compound nouns with more than two words are potentially ambiguous (see the title of this post). Consider the following sentence:

The ABC file configuration program was not installed on this computer.

I can have the following three interpretations of this sentence:

• The configuration program of ABC file was not installed on this computer.
• The program of file configuration of ABC was not installed on this computer.
• The program, called ABC, of file configuration was not installed on this computer.

If clarity requires a few more words, use them. If you cannot avoid using three- or four-word noun phrases, use hyphenation to remove potential ambiguity. Consider the following revision:

The ABC file-configuration program was not installed on this computer.

Sounds better?

(3) Do not begin a heading with a verb

Consider the following sentence:

Print the Expense Summary

Are you telling a reader to go ahead and print the expense summary (in which case the heading's fine) or are you trying to tell a reader how to print an expense summary. If it's the latter, do add a "How to..." at the beginning of the heading - it orients the reader to your think-track.

Again, consider the following sentence:

Printing the Expense Summary

Do you mean that you (or the printer) is at this moment printing the expense summary or do you want to describe the process of printing the expense summary?

(4) Do not embed text in images

Else, it will take that much more time to do the following:

1. Extract the source text from the image.
2. Create a duplicate image minus the text.
3. Insert the translated text back into the image.

Or, if you cannot avoid doing so, be aware of the extra effort needed to localise the images.

(5) Do not expect the translators to be familiar with all sorts of content-authoring tools

You may have Vista-equipped workstations that run Structured FrameMaker, which integrates seamlessly into Webworks to produce beautifully compiled help-files. Your documents may be stored as XML modules. But do not expect all translators to have all the software that your company uses or to be familiar with XML and HTML tags. You have the following possible solutions:

• Send across the source text in a format that is editable by the majority (examples: Notepad, Word, Excel) and budget for the effort needed to rework the translation in the format that you want.
• Pay the translator for software that the translator may have to buy to cater to your special needs, and train the translator to use that software
• Look for a translator who can handle the file formats that you use.

Each of these options has a cost-time trade-off that you have to evaluate.

(6) Share your glossary with the translator

In other words, speak the same language. If you think that "trend graph" plots more than one Y against time X and your translator thinks that "trend graph" is a graph that shows the change of one Y against time X, then we are not speaking the same lingo.

Similarly, if you have a terminology in the target language, share it with the translator.

(7) Provide for text expansion and contraction

Be aware that translations to other languages may take up more space or less space than the source English text. Arrange your page layout and document layout to accommodate the variation. This may be important if your manual gets packed in the same carton as the software, and suddenly you find that the document is bulkier or larger than you what you planned.

The same holds true for UI elements. If you can have a say in the UI design, arrange the buttons and captions in such a manner that expansion and contraction of text is taken care of.

(8) Be available to answer queries

Make that extra effort to reach out to a team you've never seen, and probably never even spoken to. Your translators may be scattered over the globe, working in a time-zone different from yours, and they may not be subject matter experts. They may often stumble upon words and phrases that are not clear to them. Budget for time-zone differences and let the translators know when they can expect a response to their queries. Remember that translators are as much pressurised by deadlines as you are and their output is directly dependent on the feedback they get from you.

I am sure there are more points, but these are the ones that I think can take care of a lot many things.

Do I speak your language

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

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. :-)
--------------------------

What am I?

Someone asked me, "So, what are you?"

"A technical writer."

"Eh, and what’s that?"

I realised that the noun phrase technical writer does not in itself mean anything at all unless it is described through attributes. So, what are the attributes of a technical writer?

1. A technical writer understands what is being documented. The writer takes on the role of the reader, and learns everything that a normal reader would know, or want to know. The writer has domain knowledge and product knowledge.

2. A technical writer has a flair for words, but neither sends the readers scurrying for a dictionary nor regurgitates all the knowledge gleaned from research. The writer documents only that much information as is needed by the readers, and does so in a no-nonsense, matter-of-fact manner. The writer knows the target audience well enough to be able to include some items of information and leave out some others. The writer engages in a dialogue with the reader, not in a monologue that showcases the extent of the writer’s knowledge.

3. A technical writer takes ownership of documents, but is so self-effacing that no one can tell who wrote the document. The writer sets aside the individualistic streak and follows a straitjacketed style guide. The writer knows and believes in the concept of uniformity.

4. A technical writer works smart. The writer knows the tools of the trade and leverages them. The writer is constantly in tune with emerging trends in authoring, and incorporates them in the work.

If I were to summarise these points, I would say that a technical writer is a language expert who understands the domain and product, has no problems with non-visibility, and makes intelligent use of tools and techniques to produce documents that make a reader go, "Ah, I see".

Genesis and a prize

I won a prize for my blog post Genesis, before Darwin, of a User Manual. The contest was organised by TWIN.

To Hyphenate or No

I am helping a friend who wanted lessons in English grammar. i find the going rather tough (having slept through grammar classes in school).

Anyways, today, I wanted to send across an exercise in hyphenation and, not wanting to go back to real-life technical documents, I came up with the following:

-------------------------------------------
It was the twenty fifth of December, in the seventy third year of the reign of Kind Edgar, that the saviour was born. On that star studded night when the gentle shepherds were tending their sheep and when the blue jays had gone to sleep, a child was born to white faced Maria. While the sandal shod husband stood and looked, the hay filled manger lit up with the smile of the child. The smile went a skipping, broke into a thousand pieces and ascended the night sky to burn a golden coloured star. The wise men in the east, who had grown old, bearded and heavy hearted awaiting the birth of the saviour, saw the star and exclaimed, "Here comes the world saviour and the sin redeemer." And they ran towards the west. Little did they know that King Edgar had started a faith based census where every evil doer would be asked the following two questions: Is it self evident that life, liberty and the pursuit of happiness is the birth right of all human beings? Is it that all passwords to Hell should be case sensitive? All such evil doers who could not submit their responses in the government issued template were to be thrice whipped and twice drowned before being hanged on the cross till death.
-------------------------------------------

Am waiting to see what happens. I am not too sure about hyphens either....

 

Of dots and curls - Part 2

Colon, meanwhile, was unhappy. He liked introducing people to other people. So, he liked throwing parties. But, his last party had been a disaster. His cousins Period, Semicolon and Comma had absolutely refused to sit next to each other; Space had scandalised everyone by insisting on sitting next to EnDash; and the Uppercases had been a pain since they brought their lowercase legions with them and expected Colon to feed everyone. Now, Colon made all his money from introducing people to other people, and couldn't really afford to feed the two, or three, or more lowercase legions that Uppercases always turned up with. And, he couldn't stop the Uppercases from bringing in their legions because the senate had enacted the Drop Cap policy.

"I know what", though Colon as a sudden idea dawned on him. "I'll turn the legions against one another. They would keep banging against each other since I wouldn't invite Period, and since I would definitely not invite Bullet."

....

So it happened at Colon's next party. And the Uppercases stood gazing upon the carnage, sighing, and thinking, "Oh, what a tangled web we weave".

 

Documenting Mjrz.net

Sometimes, I wander around at sourceforge.net just to see what's happening in my areas of interest (finance, languages, ...). On one such trip, I chanced upon a "Help wanted" for documenting a financial software. Right up my sleeve, I thought, and wrote to the developer.

That was about a month and a half ago.

Today, the documentation is up and running at the software website: Mjrz.net Personal Finance Manager*. Despite some teeny-weeny bugs in the doc, I am going around with a huge grin on my face - it gave me a thrill to see my name in the credits :)

* The project has since ceased to exist. The link will no longer work.

Of dots and curls - Part 1

Once upon a time, in a hut far into the woods, there lived a little boy called Comma. He had a curl in his cap, a spring in his step and a lot of envy for his two elder brothers. The eldest brother was called Period. He was ponderous and slow, and hated it when Comma ran in circles around him. Comma was jealous that Period always got the final word in any matter. And then, there was the middle brother, Semicolon. Since he hardly ever spoke unless spoken to, Semicolon gave out an air of profound thoughtfulness wherever he went. And that is what made Comma look upon Semicolon with a bit of awe. "Wow", he would tell himself. "He speaks rarely, but when he does, he can snap stuff into two. Without killing them off like Period does."

So what was it, actually, that Period did that annoyed Comma so? It was the fact that whenever Period said "Hey, here I come", things would stop. Immediately. People would have to begin afresh. Pick themselves up, don an upper case and continue. This was totally against Comma's firmly held belief - never make people change their cases unless they really really want to. Lower cases were lighter to lug around, and merged well with others. Upper cases? Well, now they were a different ballgame altogether - they towered over others, gave others an inferiority complex, and even sprouted shoots and leaves just for effect. No, upper cases were definitely not on the list of Comma's favourite things. The last time an upper case had stood next to Comma in the queue, it looked down its nose at Comma, sniggered, and said, "I represent Proper Noun".

 

Translating WikyBlog to Bengali

I am translation WikyBlog to Bangla and it's already 48% done in three days. :) Once I complete Bangla, I'll take up Hindi.

 

Documenting TransProCalc

A few days ago I was idly browsing the Proz site (www.proz.com), which I am helping localise to Bengali. In the forums there, I saw an announcement by Anthony Baldwin - he had created a small software for managing documentation projects, and had put it up for free distribution. I was intrigued, and downloaded and played around with the sofware. Then, I asked Tony if he would let me document the software.

He agreed :). Thanks Tony for letting me document TransProCalc.

This is the help document I wrote and Tony edited. (Update as on 07 March 2010: The link no longer works. The new URL is http://www.baldwinsoftware.com/tpcalc_manual.html.)