Writing Technically

When the ToC spins out of control

noreply@blogger.com (Anindita) — Sat, 19 Sep 2009 12:13:00 +0000

-------------------------------------------------------------------------------------------------

This post has a post script written about 45 days after the original post.

-------------------------------------------------------------------------------------------------
Early this year, I wrote the install guide for an enterprise-level reporting application. The application itself is pretty easy to use - once it's installed properly - with intuitive UI elements etc. It's the installation that's a bit complicated. The product has three separate components which, while they can be installed on a single machine, will in a real scenario be installed on three (and possibly four) different machines. Let's say the components are A, B, and C. The installation order should be, in sequence,

Install and configure A
Install and configure B
Install and configure C

The steps differ for Windows and Unix. So, at first, my ToC looked like this:

and the expanded ToC looked like this:
Thereafter, things got murkier. A and B ride on top of pre-installed RDMSs, which effects the configuration steps. The installation itself has two threads - manual and automatic - which further complicates matters....

Version 1.0 of the product was releasing, like, day-before-yesterday, and without much time on hand, I ended up with a document that had the following ToC:
Every time I looked at it, I puked. But my dev team loved it - they found navigation a breeze and assured me that it'd be sysadmins who'll be reading such install guides and sysadmin minds work pretty much like theirs, and NO, it would not be a problem for the reader.

Two months into the release, the product is well-received, we're working on an upgrade and feedback starts trickling in...the install guide has all info but it's difficult to figure out what is located where...once I am at a page, it's difficult to figure out what's Next and Prev...there are too many "related links" on a page and I get confused (this last bit is not my doing - it's a DITA thing. All subtopics in a "family" or a "sequence" topic get automatically linked to each other).

In short, nope, sysadmin minds were not working the way the dev team said it does. I pretty much suspect a glazed look came over their eyes when sysadmins expanded the ToC and saw all those nested and more nested topics. I also suspect none of the sysadmins read the checklists and high-level steps I'd included in the "Planning the installation" topic.

In this post, I am thinking aloud about restructuring the ToC. Here's what's on my mind:

So, instead of readers navigating like this:

they can now navigate like this:
Am still thinking, though, if there's a better way to present the information...
-------------------------------------------------------------------------------------------------
Post script
I am leaving the ToC alone. What I'm doing is pulling out a buried topic and moving it right to the top, plus calling it prominently in the default home page of the online help. This topic has an installation matrix, and road maps for common deployment scenarios. People, when pointed to this hitherto-unseen topic, exclaimed, "Thanks! This is tremendous help."

Lesson learnt
Findability is important. In-your-face findability is absolutely important.

[aside]"She dwelt among the untrodden ways...Half hidden from the eye! Fair as a star..." [/aside]

Dated: November 6, 2009
-------------------------------------------------------------------------------------------------

Bad docs rarely mean bad sales

noreply@blogger.com (Anindita) — Sat, 04 Jul 2009 04:03:00 +0000

My father is more than 65 years old - which means he is officially a "senior citizen" entitled to tax breaks, travel concessions, blah blah. It does not, however, mean he is entitled to special consideration from his children (who continue to treat him like he's the dad that dropped them off to school but often mixed up the timings of the son's school with the daughter's).

So, when I got a blank SMS from my father (a few days ago, he'd been given a cell phone by my mother), I did not panic. I calmly rang him up (from 1500 kilimetres away) and asked, "Why on earth did you send me a blank SMS?"
"Did I? But I am still trying to write the message; how did it reach you already?"
"Oh? Did you ask Mom to show you how to write messages?"
"No, she's in the shower. I thought I'll look at this tiny booklet that came with the phone."
"And?"
"This is what it says under 'Message'."

"Hmm, did you press 'Send' after you wrote the message or before?"
"I could not figure out Step 2. It says 'write'. How do I write? I want to type H, then O..."

Problem 1: Step 2 does not say how to write a message, neither does it link you to another place in the doc that might have instructions on how to write the message.

"Then you must have pressed 'Send' before you typed anything. Now, look carefully in the manual and see if there's a topic called 'Writing a message' or similar."
After 2 minutes of silence,
"Yes, there is something called 'Write text'."

"Okay, so now you write the text and send it to me."
"No, wait, it says 'press the key repeatedly'. Which key?"

Problem 2: Which key does "the" refer to?

By this time, I had lost patience and mom had finished her shower, so, within 5 minutes I got an SMS from dad. It read "How were the mangoes we sent across last week?"

How was this episode relevant to me as a technical writer? Let me count the ways:

It reinforced two of my firmly held beliefs:
1. Do not assume your reader to be as tech-savvy as you might be. Do an audience analysis and write for the lowest common denominator (remember Manmohan Desai and Prakash Mehra?)
2. Do not make the reader go hunting for bits and pieces of info. Give complete instructions in one topic. It's okay to be verbose if that's what it takes to completely describe an action.

It added one more incident to my observation that badly produced "help" rarely effects buying decisions. Not at the retail level, anyway. I'll still go buy a handset from this equipment manufacturer because their handsets are good.

Which might mean - technical writing is a cost activity, not a revenue or a profit activity.

INDUS Apr - May 2009 released

noreply@blogger.com (Anindita) — Mon, 25 May 2009 17:15:00 +0000

What's there in the second issue of INDUS ( http://stc-india.org/indus/index.htm )?

Take your pick:

How do we continue to grow in our career? Kumar Dhanagopal tells us to never stop learning.
What does Web 2.0 mean to us, writers? Preran Kurnool shares his thoughts and David Dick reviews a book on Web interface design.
Are conventions and style guides sacrosanct? Sharada Palagummi and Suman Kumar raise these questions in their two separate articles.
Want to know about the principles of instructions design? Begum Laila Kamal reads a book on it and summarizes the points.
Looking for community announcements? See Tidings.
What's new? There's a Lounge. And, like you told us in the survey last year - you wanted a downloadable PDF version of INDUS, so we've put that in. There's also a mail-a-friend link for all the articles.

We hope you enjoy reading this edition. As we strive to make INDUS more meaningful to you, we always look to you for inspiration, ideas, and feedback. Do drop us a mail with your thoughts, or leave your comments here on the blog.

Task flow - Analysed?

noreply@blogger.com (Anindita) — Sat, 16 May 2009 10:39:00 +0000

I took the following screenshot from the website of my credit card company. I was at the website trying to see if the payment I had made yesterday had been effected.

What is not quite right in the picture?

Would it not be better to tell me (the user) right away that if I use PayNet (which I always do), I cannot see my payment history through this interface? That, if I want to find out the status of my PayNet payment, I would probably need to call up customer service?
How about the following picture?

Is it not simpler, smaller, clearer? Does it not communicate upfront about what it can do and what it cannot?

Now, if only the designer who created the user interface had approached the interface as a user would have...

What is the point in telling me AFTER I have selected the dates , clicked Go, and waited for a few minutes, that I cannot view my payment history if I paid through PayNet?

Website users have a short attention span and do not read the entire page from top to bottom before they begin doing the task at hand. They quickly scan for the numbered steps, and start off following the instructions step-by-step. If the prerequisites (or, limitations) are not stated before the numbered list begins, the users can only get frustrated. Like I did.

User scenarios, anybody?

noreply@blogger.com (Anindita) — Sun, 10 May 2009 10:47:00 +0000

It was while leafing though the microwave guide, trying to find something, that I realised those good souls at the techpubs department of the microwave company had probably not done a user-needs analysis.

Before we go any further, let's first profile me. Female, Indian, grew up on mother's cooking, manages a home and a career, hates eating out, is always rushed for time. A microwave, they say, is handy for such people. It even (!) cooks Indian food without using as much oil (or time). So, fine, here I was trying to cook Indian food. I was making myself some aloo-dum and wanted the steps to:

Heat oil on high, throw in the seasoning, reduce heat.
Wait for a minute, increase the heat, throw in the aloo cubes, stir, cover.
Wait for two minutes or so, reduce the heat, let it cook.
Take out cooked aloo-dum and eat with puffed rotis cooked separately.

I was looking to combine steps 2 and 3 - I wanted to keep the stuff on increased heat for a few minutes and then get the microwave to reduce the heat automatically without manual intervention.

The microwave guide had no instructions for this scenario. Which means, I had to hover over the microwave for two or so minutes, manually reduce the heat, and ...
Two minutes is a long time for anyone rushed for time. Heck, even a Hindi film song gets over in two minutes. If I have to hover around the oven for two minutes, I might as well use the good old gas burner. So, I remembered the techwriter's Law No. 1: RTFM*

I did. And found nothing. It has a nice section on Indian recipes, with nice preset buttons that you can use to cook stuff. Nice. But it still did not tell me anything about setting the cooking cycle for multiple stages. The closest it got was this:

No, I wasn't cooking chicken tangdi kebab, thank you.

All Indian cooking, if my knoweldge serves me right, goes through a cycle of increase heat -> decrease heat -> increase heat -> decrease heat. This manual, meant to accompany a product that was being sold in India for Indians, didn't tell me how to.

* RTFM stands for Read The Fucking Manual. Back

Just in case you're wondering - the brother figured it out. He looked at the manual, tossed it aside, looked closely at the buttons, tried a few press this - press that combos with still-raw food (we ate it after those several experiments of his), and figured out the combo. I'm not sure if I'll ever look at that manual again.

The engaged reader

noreply@blogger.com (Anindita) — Fri, 01 May 2009 10:08:00 +0000

I was at my neighbour's. Their seven-year old boy came out of the room, put on his going-out chappals, and was turning the door-lock to open the door and go out when his mother said, "Why are you going out? Should you not be studying for your English test tomorrow?" The boy replied, "There is no more space in my brain."

We live in an era of information overload, the just-google overload. And, because everyone can write (!), we also live with community-contributed growliths such as Wikipedia. Here's a picture of a Wikipedia page that is trying to tell you what Twitter is about:

Noticed the excessive linking? There's a hyperlink in almost every sentence. Most of the time, the hyperlinked words have no relation whatsoever to the task at hand (which is, explaining what Twitter is about). Here are the superfluous links:

But just because the information is there - somewhere - on the Web, it HAS to be linked. ! @ # $ % And never mind the distraction - or the possibility of the reader clicking such a link and navigating away from the page and on to a (duh!) competitor's page (like, Facebook). The reader would be walking away from the page, declaring there's no more space in the brain. But hey, wait, was it not your goal to engage the reader?

Here is a screenshot of something that resisted the urge to overlink, and succeeded in keeping the reader focussed.
Noticed the immense possibilities of linking this paragraph provides? Almost every bullet point screams "Go, Go, Go". But because there's no clickable door to leave, the reader stays on the page. Engaged.

Style Quiz - The Economist

noreply@blogger.com (Anindita) — Sun, 12 Apr 2009 17:23:00 +0000

The Economist has a quiz up at its site. I took it and got 9 out of 12. What does that mean? Well, this:

If you too want to take the quiz, click here.

Writing for the vacuum

noreply@blogger.com (Anindita) — Wed, 01 Apr 2009 17:13:00 +0000

I write for people I never meet and most likely never will. Of course, we have stuff such as "audience analysis" that helps us frame a mental picture of the reader we are writing for but, in reality, I write for people I never meet.
Consequently, I never get feedback from my readers. Of course, we have review rounds, and we have tech-support reading our documents and troubleshooting, and all that stuff but, in reality, the user for whom I wrote the manual never gets back to me. Usually.

This is a pet gripe of the techwriters I've met. "We don't get feedback from the real reader", is what they say.

True. But hang on! How many of us techwriters have ever given such feedback ourselves? How many of us have even bothered to look at this and give feedback:

What happened to the Do Unto Others principle? Why carp when you're also the one who cannot cast the stone?

Word Mutants

noreply@blogger.com (Anindita) — Thu, 26 Feb 2009 04:04:00 +0000

The Washington Post's Mensa Invitational had asked its readers to take any word from the dictionary, alter it by adding, subtracting, or changing one letter, and supply a new definition. I thought that was fun, so here's my attempt:

With a letter added

prayfer: a prayer for the appearance of a specific object in the Christmas stocking

compunter: a computer that helps you place bets on software-offshoring companies in yet-to-be-developing nations

sufferling: a child of insufferable parents

abstinthe: to abstain from drinking absinthe while reading Wodehouse

extravagrant: to stay out of suitcases in the presidential suites of grand hotels

celeberate: when clueless celebrities gather in a TV studio to berate the policies of the government

With a letter deleted

banstand: a covered outdoor platform, across the busiest crossing of a city, where crowds gather for lighting candles to fight terrorism

univerity: a college that preaches universal truths

faceboo: to join a Facebook group created for taking potshots at a person, an object, or an idea

With a letter changed

inferface: a biometric interface that has sensors to figure out if your face has the characteristics of a jihadi killer

singelton: a gay singer

designame: to create self-explanatory designations from proper nouns. For example, Chief Satyam Officer

conpetition: a pre-judged competition on a TV reality show

euphomia: the feeling of intense happiness experienced by a megalomoaniac

Wishing my blog readers a happy 2009

noreply@blogger.com (Anindita) — Mon, 29 Dec 2008 09:54:00 +0000

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

noreply@blogger.com (Anindita) — Sat, 20 Dec 2008 16:09:00 +0000

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

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

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.

Export Robohelp files as Word files, proofread.

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

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:

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.

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

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

noreply@blogger.com (Anindita) — Sat, 13 Dec 2008 14:31:00 +0000

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

noreply@blogger.com (Anindita) — Sat, 06 Dec 2008 15:55:00 +0000

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

noreply@blogger.com (Anindita) — Tue, 02 Dec 2008 05:13:00 +0000

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

noreply@blogger.com (Anindita) — Sun, 30 Nov 2008 18:44:00 +0000

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

noreply@blogger.com (Anindita) — Tue, 25 Nov 2008 09:17:00 +0000

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

noreply@blogger.com (Anindita) — Fri, 21 Nov 2008 17:20:00 +0000

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?

INDUS: Sep - Oct 2008

noreply@blogger.com (Anindita) — Mon, 03 Nov 2008 07:33:00 +0000

The Sep-Oct 2008 issue of INDUS was released two minutes ago.

Matters of Ownership (ethics)

noreply@blogger.com (Anindita) — Sat, 11 Oct 2008 17:34:00 +0000

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

noreply@blogger.com (Anindita) — Sat, 04 Oct 2008 15:51:00 +0000

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.
Select File > Print > Page.
Ensure that you are logged in to the YSQT domain.
Ensure that the shared printer appears in the list of printers configured for your machine.
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

noreply@blogger.com (Anindita) — Wed, 01 Oct 2008 14:31:00 +0000

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

noreply@blogger.com (Anindita) — Wed, 03 Sep 2008 14:25:00 +0000

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 the following sites and following actions to be useful:

Wander around at sourceforge.net, look for "help wanted" for documentation, and volunteer. 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.
Peter Grainge's site: http://www.grainge.org/
TW mailing lists such as the TWIN mailing list and TechWrl, and Internet groups such as the Yahoo group technical_writers_india.

INDUS: Jul - Aug 2008

noreply@blogger.com (Anindita) — Thu, 28 Aug 2008 11:24:00 +0000

The latest edition of INDUS - STC India's newsletter - hit the stands a minute ago :).

What is Technical Writing

noreply@blogger.com (Anindita) — Fri, 15 Aug 2008 17:50:00 +0000

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

noreply@blogger.com (Anindita) — Fri, 15 Aug 2008 14:55:00 +0000

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.