Wednesday, December 5, 2007

Translating Tagore

The Sahitya Akademi, in July this year, advertised a literary translation competition in the leading newspapers of the country. The Akademi is celebrating the 50th year of publishing translations through its journals; hence the competition. Entries were invited - translations from Indian languages into English in the genres of poetry, short fiction and oral literature could compete for the following prizes:
  • 3 first prizes, one each in Poetry, Fiction and Oral Literature, of Rs.10,000/-
  • 3 second prizes, one each in Poetry, Fiction and Oral Literature, of Rs.7,500/-
  • 3 third prizes, one each in Poetry, Fiction and Oral Literature, of Rs.5,000/-
  • 5 consolation prizes in Poetry, Fiction and Oral Literature, each of Rs.2,500/-
  • 50 consolation prizes, of a one-year subscription to the Akademi's bimonthly journal Indian Literature

My entry, Subha, a translation from Bengali into English of a short story of Rabindranath Tagore, won a prize in the last category.

I am thrilled to bits. My entry will actually get published in the Akademi's Indian Literature. Wow!


Sunday, November 25, 2007

Support Cases and Documentation

Yesterday, I attended a meetup, of the Bangalore Technical Writers group, where Vasanth Vaidyanathan of Sun Microsystems spoke about using support cases as inputs in the documentation maintenance phase. The thrust of his talk was that:
  • support engineers are at the ones who interact with customers and who help fix customer problems,
  • support engineers know the problem areas in the product (a "problem area" being one that generates the maximum number of support calls),
  • the documentation team, with a little help from the development team, can figure out whether documentation could have pre-empted such support calls,
  • the documentation team can thus, by studying the support cases logged by the technical support desk, gain real customer feedback on documentation,
  • such customer feedback can go a long way in planning for the maintenance of legacy documents.

I agree with Vasanth's viewpoint. It is a novell (in my knowledge) approach to getting customer feedback on documentaion, and tackling the problem areas that may exist (in the documents).

But for service companies, like the one where I work now, access to support desk data is almost non-existent. We develop the product, ship it to the client, and that's about it. Who gives us feedback? Our client, who is NOT the end user (the "customer").

So, I was wondering how to adapt/adopt the support-case strategy to the documentation cycle of service companies.

I posted a question at the Technical Writers of India yahoo group and got some responses. I'll be summarising them in a couple of days.


Wednesday, October 17, 2007

The Story of a User Manual

I often hear questions like "What is a user manual" and "How do you write a user manual" from new technical writers. This is what prompted this write-up. In the next few paragraphs, I will describe the steps that go into creating a user manual. At the end of this write-up, I hope to have answered the questions that I started with.

In the beginning, there was the Word.
There'll be reams of paper to wade through. There will be the software specifications, the software requirements, the user requirements, the notes jotted down by the developers, and sometimes, a user manual of a previous version of the product. It does seem a bit mindboggling at first, but that is exactly what Technical Writing is about – spreading the Word.

Then God said, "Let there be light", and there was light.
We, as technical documenters, introduce a product to a user. So, it is essential that we have a clear understanding of the product that we're documenting. How do we go about it? We read the legacy documents, we play around with the product, we study the domain that the product belongs to. Why is the last so important? Well, if we are documenting the GGSN server, for example, it helps to know at least the fundamentals of networking. This is the stage where we get our concepts right, and clear our doubts about the whats and the whys (tackling the hows come later).

And God separated the Light from the Darkness.
Too much of light can be blinding, and things do tend to seem clearer when viewed through filters. So, we parse the information. What we are writing is a user manual. Who is this user? A system administrator? A shopfloor engineer not very familiar with Windows operations? What would such a user use the manual for? Troubleshooting? Operating? Installing? A bit of all three? We analyse the reader requirements, and create a skeleton for our user manual. We arrive at the broad outlines of the information that will go into the manual, and the organisation of such information.

Then God said, "Let the earth put forth vegetation: plants yielding seed and fruit trees of every kind."
Armed with an understanding of the product, and of the user for whom we are writing, we now get down to the actual business of writing. And illustrating, if needed.

God made the two great lights – the greater light to rule the day and the lesser light to rule the night.
Lights help us navigate. The TOC is a broad navigational aid; the indexes and the glossaries are those little extras that render a document that much more user-friendly. A highly technical reader does not need definitions but if our intended users cover a broader spectrum, we need to include a glossary. An index is an absolute essential for any document that has more than one chapter but it does not help much if all the index entries are mirror images of the TOC entries. Why? Because a reader turns to an index (or a search) only after failing to find the information in the TOC.

Then God said, "Let us make humankind in our image."
We now have a document. But we have not tested it yet. Is it in the "likeness" that we intended it to be? We pass on the document for review – usually the development team will do it but if they are too busy tackling last minute enhance-requests, and fixing those murphys-law-bugs, they may not exactly be disposed to read our document and review it. In such a scenario, it is best that one sits with the document in one hand and the product in the other, and see whether the two match. If it is an installation guide – do the steps described in the document yield exactly the same result that the product is now showing me on the screen? Has the GUI changed in the time that I last saw the product? Is the product now called something else? We check all these and correct our misses. Then, we pass it on to a language editor, get the review comments and incorporate them.

And on the seventh day, He rested.
But before resting, we ensure that we've followed all the version control policies. Then, we can take our team out for lunch.

This, in brief, is the genesis of one of the main deliverables created by the technical communicator community.

And then, there's Darwin but that's for another day.