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?