Writing Technically

Techwriting lessons from films

2011-12-07T01:51:00.002+05:30

This post contains what I presented at the STC India annual conference of 2011 at Chennai.

We'll go straight to the first of the film clips. [The videos might take a while to appear on the page. Depends upon the internet speed.]

When chess pieces go missing

The lesson I learnt from this movie sequence? That I need to be more concerned about my core skill (writing) than the tools I am using to practice that skill. That, as a writer, my other core skills must be agility, resourcefulness, and adaptibility so that I can work with whatever is available to deliver that which is deadlined.

On to the next lesson.

You have to ask me nicely

As a writer, I am on cross-functional team meetings, I test software, I file defects, I coax people to share their knowledge…I need to know the people I am talking to. And, I need to ask them nicely. Because, I work with talking-feeling humans for:

Getting information from the development teams
Getting the technical and editorial reviews done
Getting feedback from customer-facing teams
Getting support from the doc team

Next clip.

Are my eyes really brown? 

My takeaway from that question was Accuracy - My writing must be free from mistakes, must adhere to facts. I must:

Write only that information which you have understood and verified
Maintain consistency of all information about a subject

On to my next lesson.

I'll speak real slow

This one is about Clarity, about freedom from ambiguity or obfuscation, about presenting the information in such a manner that it can be understood the first time

Here, let me show you a film sequence that demonstrates what is not Clarity.

I'll speak real slow

Now, I'll show you a scene from a Sunny Deol movie.

Dropping down dead

Some docs are so heavy, trying to read them is like being hit by a ton of bricks. Docs that knock me down dead. The lesson I learnt from Sunny's killer punch is about Retrievability and Organisation. About how my documents must:

Provide helpful entry points
Facilitate navigation and search
Give an index
Provide you-are-here indicators
Suggest links to similar or related information

Next on to my all-time favourite Kamal Hassan movie. No, I don't understand Tamil, the language that this movie is in but hey! this clip doesn't need me to know Tamil.

What language was that

This one's about Style, about the correctness of writing conventions, and of words and phrases. What I learnt from this film sequence is that I must always:

Use correct grammar, spelling, and punctuation
Follow template designs
Use boilerplate text
Follow style guidelines

Here's the next clip.

When you have to shoot, shoot

My lesson? Task orientation. I must focus on helping getting a job done. I must classify my information by its type so that I can:

Create docs in a consistent manner, so that the right design gets used (for example, tables for reference information, step sequences for tasks)
Focus on tasks, and move the supporting concepts and reference information into other topics, where they can be read if required and ignored if not

When my information is focussed on the task at hand, stripped of all supporting information, here's how I can help people get their jobs done.

When you have to shoot, shoot

And now to the last of the film clips.

Broken bones

This one's about Visual effectiveness, about how I should:

Ensure that all users can access the information
Use graphics to complement the text

Acknowledgements 

Films: Shatranj Ke Khiladi, A Few Good Men, Casablanca, Deja Vu, Fandango, Damini, Salangai Oli, The Good The Bad The Ugly, Beverly Hills Cop, and Rear Window
Books: The IBM Press book called Developing Quality Technical Education

Recasting the recipe

2011-03-22T15:49:00.006+05:30

Just because I do something well does not necessarily mean I like doing it. Cooking, for example. Hence, I steer clear of all recipe booklets, cooking websites, and similar. But a weekend conversation on FaceBook about things planned for the Holi break needed me to sit down and write a recipe for my friend, fellow techwriter Samartha Vashishth. One look at my mail and he wrote back saying "put in blog post" etc. Hence.

I know the first list in that recipe should've been an unordered one. :-)

Let's take our edit hats off while we look at the recipe, shall we?

How is it different from standard recipes? Here's how:

It assumes you are doing only this task and nothing else. There's no "Do X and keep aside" instructions (despite possibilities); there's only a linear task flow.
Lesson for techcomm: Do not introduce branches into a procedure.
It does not just list the ingredients but group them according to when they're going to be used in the process and what they're going to be used together with.
Lesson for techcomm: Grouping of logically related items aids in (i) comprehension (ii) task completion.
It does not have pictures :)
Lesson for techcomm: Use pictures only if they are essential to performing the task.

How I could've made it better? Listed the utensils, perhaps. No recipe that I've come across ever lists them (except, maybe, cakes, and that too a grudging 5" baking tray mention) even though they are very important to the task at hand. Notice how, in step 9, I suddenly introduce a utensil (bharta toaster) that is otherwise not logically related to the cooking of haleem? Bad!

Tweet, don't twitter

2011-03-09T14:41:00.002+05:30

"Talk rapidly and at length in a trivial way * " is what prompted this blog post. I've been on Twitter for close to two years now and thought it was time I compiled a "Thou shalt not" list for tweeting. So, here goes:

Do not use "Pls RT". Not only does that use up six characters, it also presumes I am not smart enough to know if something is good enough to be shouted of from rooftops. That, and the fact I hate being told what to do.
Do not use up all 140 characters unless unavoidable. Leave enough room for your twitter handle (if someone wants to RT) and some comments (from people who're sharing your tweet). The first is self-promotion, the second is courtesy.
Do not tweet ONLY to share your blog post URLs. Thanks, but we have feed readers for that.
Do not keep retweeting like there's no tomorrow. If we are linked through Twitter, there's a 1 in 2 probablity that our Followed list is very similar. Retweets by you clog up my timeline. If you find yourself retweeting stuff too often, consider putting those tweets into paper.li and sending out ONE single paper.li-automated tweet daily. Besides, if all that you do is retweet, I am going to Unfollow you within a week (unless what I was looking for was a human feed-aggregator. For free).
Do not just retweet - tell me why you thought it was retweetable (see #2).
Do not be a radio commentator on the sports field. If I am as enthusiastic about that game as you, I am watching it (and not reading your tweets). If I hate sports, you're clogging up my timeline and, No, I can't filter you out because you never use hashtags and words consistently. This holds true not only of sports but of TV programs as well.
Do not tweet something that wouldn't make sense to 50% of your followers. What, you do not know about your followers? Bleh! You talking to chairs and tables, then - where's the point?
Do not tweet long updates one after the other, 16 tweets to a minute for 3 full minutes. If you have lots to say, use Twitlonger (or whatever) or write a blog post.

As with life, so with Twitter - do not blabber and do know who you are talking to.

--------
* One of the definitions of 'twitter (verb)' given by the Oxford dictionary

Disclaimer: Sorry for the rant post but I just had to. Rant, i.e.

Listen! Do you want to know a secret?

2011-03-05T21:16:00.000+05:30

Let's start at the very beginning
A very good place to start
When you read, you begin with A-B-C

A is for Adobe. The company that left Anindita with the distinct impression that it thinks that that the techcomm world revolves around it. Also see F and R.
B is for Beta. It stands neither for the second letter in the Greek alphabet nor the second brightest star in a constellation. It stands for not-yet-ready releases and is an excellent medium for techcommers to get feedback on their work.
C is for content. That which makes the techcomm world go round.
D is for DITA. That thing which cures all ills. Sane voices suggest otherwise but people still see through the glass darkly.
E is for English. A language much maligned by a tiny, pint-sized apostrophe, which, if misaligned, can even become a comma. E is for editors. That group of people who are haplessly left with correcting the thats and whichs when what they’d dearly like to do is spend time on indexes, navigation, and coherence and cohesion.
F is for FrameMaker (See A). F is for feedback. A message where the message is often confused with the messenger, often unjustly.
G is for Google. It is a help authoring tool that saves a lot of SME time (see S).
H is for Help. A verb and a noun (See the possibility related V). Help is a privilege. You may want it but not get it.
I is for information. Information is a noun that cannot stand on its own; it must always be used as an adjective. Information design, information architecture, information developer, and information overload, for instance.
J is for coffee and pictures. As in, Java and JPEG.
K is for knowledge. Of, besides writing, the tools, domains, and processes.
L is for listening. It stands for the characteristic of being alert and ready to hear anything that might lead to knowledge (see K).
M is for multimedia, an umbrella term for anything that moves, creates noise, and can be packaged.
N is for No. As in, “No, I will not document how it should work; only, how it does indeed work”, “No, I will not put this screenshot here because …”, “No, this will not go into an install guide because….”
O is for obfuscation. So long as obfuscation exists, so will a technical communicator. If you do not know what obfuscation is, here is an example: “The relationship, which I might tentatively venture to aver has not been without a degree of reciprocal utility and even perhaps occasional gratification, is approaching the point of irreversible bifurcation and, to put it briefly, is in the propinquity of its ultimate regrettable termination.”
P is for PDF. It was born in 1993. Other births that year include Microsoft Windows NT and the republics of Slovakia and Czech.
Q is for curiosity. Why should I…? How does this…? When will it…? If I do this, what will….? What’s the difference between…? What is the weight of the moon?
R is for RoboHelp (See A). R is for respect. An emotion that causes much existential angst among techcommers.
S is for scrum. It means giving daily updates to your team and then running back to do the work you yourself promised to. S is for SME. It means the fount of knowledge from which information must be gleaned. S is for substance (See C). S is for style. It is something best only followed, not tampered with.
T is for Twitter. A medium used almost exclusively to pimp blog posts, product launches, and rave reviews. T is for TWIN. Bonded for life.
U is a letter so important that it must never be used in isolation. U is royalty and must always be teamed with other letters, like this: UX, UA. U is the reason techcommers exist; U is for users.
V is for vision. That which makes techcommers put descriptions in alt text, pick the reds and greens with care, and prefer lists to tables. The ability to see beyond the obvious, to ‘write’ for everyone.
W is for wiki. Everybody knows it’s there but nobody knows what to do with it, hoping that somebody comes up with a wiki-to-source roundtripping that helps anybody adopt a wiki.
X is a placeholder. As in XML.
Y. A letter for which I could not come up with a word. I did try to match it to words such as Yes, Year, Yearn, and Yesterday but felt something was missing. So, I am leaving Y alone. For You, the reader.
Z is for zen. And the art of writing for motorcycle mechanics.

When you know the notes to sing
You can sing most anything

====================================================

This first appeared in the Nov-Dec2010 issue of INDUS, STC-India's newsletter.

Acknowledgements

Rachna Singh Ganguli for G = Google, F = feedback, Help is a privilege, J=Java and JPEG, R = respect; T=TWIN.
Anagha Bhat-Chandratrey for K = knowledge, L = learning.
The Beatles, for “Listen! Do you want to know a secret”.
The people of The Sound of Music (1965) for “Let’s start…with A-B-C” and “When you know…most anything”.
The people of Yes, Minister (BBC) for “The relationship…termination”.

Woo hoo! Smart search is possible

2011-02-18T09:24:00.002+05:30

Watson had not been on my mind when I wrote my last blog post. In fact, if you were to shake me awake in the middle of the night and say, "Watson!", my immediate response would have been "Elementary, Holmes!" Despite being vaguely aware of a project called Watson underway in my company, the name didn't really mean "Wow" to me till, well, last night. But before I tell you why, let me go back a bit - and talk about my last blog post. In that post, I had implied 'storage' and 'retrieval' are two different things and, while tagging and indexing might work when one is storing something, the same tag or index could fail while retrieving the data. In my post, I had put foward a question - should content be context insensitive for it to be reused effectively? Conventional wisdom - that which runs search engines and SEO jobs - says, "No".

And then came along Watson, and beat two people in Jeopardy to win an indecent amount of money, which, it was declared, would be given to charity. A computer beat two awesome humans.

Somewhere halfway through this video, when analysing why Watson got 'Chicago' wrong, you'll see the IBM engineer say something like "the info was stored in sectors but this was not about discrete compartments" or something to that effect.

Exactly! Human brain does not process information in linear paths. It hops, skips, jumps, runs around in circles. And, because we're getting there - with Watson's help - I think in my lifetime at least I'll see content being reused in ways that I (the writer) never imagined it could be because the user (with help from Watson) is retrieving just that much - and only that much - information that the user needs. Correctly, every time, the first time. Smart user!

Lose that tag please

2011-02-10T13:34:00.006+05:30

It all started last night when I tweeted some Hindi film dialogues (In India, we have two major religions - films and cricket).

(to zoom, click the image)

And then, we got around to discussing the bestest comedy film that's ever come out of Bombay. And, this was the tweet that got me to writing this blog post.

(to zoom, click the image)

How is this relevant to techwriting?

Well, if I were an indexer, I'd have probably tagged all my film content with some of these words: bombay, bollywood, hindifilm, <nameOFfilm>, <nameOFstar>, and so on? Very search friendly and all. But say, my reader was a sociologist researching corruption in India (ahem!). This dialogue ("Thoda khao, thoda phenko" #epic) would never even show up in the search results, yet it contains exactly what the sociologist is looking for - the entire social mileu from which the phenomenon has sprung (including the defence mechanisms people employ to forget the misery it produces).

So, how did I link this dialogue to scams (that are occupying the entire front page - and more - of newspapers these past weeks)? Because in my mind, my content database is neither indexed nor tagged. I can pull out random references and tag it to anything random and yet make it look relevant.

Me: To copy, perchance to paste; Aye, there's the rub for in that paste what copies might come when we have shuffled the platforms and the versions out of the filters.
Colleague: Coils. Not filters. Coils.
Me: Coils.
<silence for one minute>

Colleague: A coil is a wrapper, right?
Me: Right.
Colleague: So, if we put a wrapper to call the boolean....

So, here I am, thinking if there is more to indexing that meets the eye. More to content reuse? More to "context"? Thoughts?

Where is the User in the Design

2011-01-22T15:48:00.002+05:30

Creation and delivery of help content was what was on my mind as I sat crocheting a tiny coin purse for my mother. She has a very cute, 3-inch, pot-bellied leather purse that she uses to keep her loose change in but it's coming apart at the seams, hence I sat there, crocheting this:

To zoom in, click on the picture

And, have we not often come across something like this:

To zoom in, click on the picture

[Note: Thanks for catching the misplaced apostrophe. Feeling too lazy to edit the pic.]

I am picturing a scenario with me and my mom:

To zoom in, click on the picture

Creating and delivering help content is very similar to creating any other product. So, I ask myself, Where, How, and When is my reader going to need this information. If I can answer these three questions, the content I create will truly be User Assistance.

Where is the user in the guide

2010-12-25T23:37:00.002+05:30

Yesterday, I got myself a new phone. Last time I had bought one, it was April 2004 - a time when cellphones here did not have built-in FM radios, internet support, multimedia messaging, and all such exciting features that are so much passé today. Consequently, it was a very celliterate me that held the phone gingerly and regarded its QWERTY keyboard with interest. And thence started my frustration. I could not figure out how to do any of those exciting features that all phones have nowadays (let's not blame the UI now. All UIs seem non-intuitive to first-time users).
So, I reached for the user guide. A glance at the ToC, and I could not find answers to any of my three questions.

To magnify the picture, click on the picture

"So what", I told myself. "Just a 37 page booklet. I'll flip through it and will surely find something."

Five minutes later, I threw the booklet away, powered my laptop on, asked Google, and found answers to all my questions:

How do I transfer a photo taken on the phone to my laptop?
Where do I get the Missed Calls list?
How do I disable the keypad beeps?

I see several things wrong with this user guide but the one thing that stands out prominently is - this guide is describing the features of the phone; it's not describing the tasks I, the user, do.

Of currency notes and information

2010-12-12T22:49:00.000+05:30

Today, I want to talk about currency notes. Indian currency notes, to be precise. Someone asked me, "How many languages are spoken in India?" Sighing with relief that the question was not the more usual "You all don't speak Indian?", I leaned over, pulled the wallet out from my pocket, extracted a 100-rupee note, flipped it over, counted something, and declared, "Fifteen officially. Not counting Hindi and English."

Users find information in the most unlikely of places. Had I been a "normal" user, the kinds that a techwriter would have had in mind while documenting something, I'd have gone to the Constitution of India website and referred to Schedule 8 - the place that lists all official languages (22, actually, till date, not including English). If I didn't know that's where the official languages are listed, I'd have run a Google search (which, in turn, leads me to the Eighth Schedule anyway). But I am not a normal user - just like most users are not normal users. Most users get their information from places that the writer might never have dreamt of.

The currency note designer, on the other hand, is very well aware of the implications of the panel that I referred to.

It is intentional - it's been put there to remind people what a greatly diverse country we are. I should know. I used to be part of our currency presses once upon a time. We used to call it the language panel. It's almost - but not quite- an easter egg *.

Which led me to wonder - do technical writers put easter eggs in their documents? I've not seen any but would love to know.
============================
* More on easter eggs: Wikipedia link

Am writing a book

2010-09-23T19:41:00.001+05:30

I am writing a book on DITA.

Yes, there are, already, books on DITA. Why, then, am I writing one? Because:

I think this book closes the gap between "what is DITA" and "how can I write in DITA".
I had wished for a book like this when I had started off with DITA.

XML Press is bringing the book out next year. Here's more on the book: Authoring with DITA.

The Myth of the Holy Cow

2010-09-08T21:59:00.000+05:30

In my life as a technical writer, I have been handed out quite a few myths [A myth, says the Oxford dictionary, is a traditional story], myths that come disguised as commandments that resound with a Thou Shalt Not. The intention, I suspect, is to lull me to passive obedience. In this blog post, I will mention some of these myths and what I think (and do) about them.

Passive voice has no place in technical writing

Before I state my position on this myth, let us recollect the definition of voice: the form of the verb that shows the relation of the subject to the action. So, the voice of a sentence shows whether the subject actively took ownership of an action and did it, or was so passive as to only be the recipient of the effects of the action.

Picture source: http://www.chumpysclipart.com/illustration/1199/picture_of_a_soccer_referee_being_hit_on_the_back_of_the_head_with_a_soccer_ball

Now let us look at the structure of a very simple sentence expressed both in active and passive voice.

Active: The installer copied the WAR files to the installation directory.
Passive: The WAR files were copied to the installation directory.

This example is a simple example and I wouldn't really prefer one voice over the other. But, consider the following example:

License key definitions are stored in a license key file, which, by default, is named lkad.dat and located in the product installation directory. If you need to modify the list of authorised servers or users, edit the license key file with any text editor.

Is there any reason why the first sentence needs to be turned into the active voice? Is there any reason why I want to know who is doing the storing action? All I want to know, if I am a license administrator, is where the file is stored (by whoever – I don’t care), what it is named, and how I can edit the license definitions it contains. Passive voice works here, and marvellously.

Upshot: When I think the doing of an action is important, I write in active voice. When I think it doesn’t matter who or what did or caused the action so long as the action got done, I don’t spend any time changing a passive voice construction to active.

Writing must be gender neutral

With all respect to all kinds of genders on this earth, I think that’s a piece of unholy baloney. In English, there is no grammatical gender. But, even though we write in English, there's every likelihood that the text will be translated to at least one language other than English. Many of these non-English languages have grammatical genders. The nouns have genders, the verbs are conjugated based on the gender of the nouns, and so on. So, something that is gender neutral in English can very well turn into a gendered phrase in a language like, say, French or Hindi.

My take is that spending anything more than 5 minutes on rephrasing an otherwise understandable and acceptable-by-usage English sentence into a gender-neutral sentence is nothing but a waste of time.

Every list should be preceded by an introductory sentence

The logic is, if I suddenly start a numbered list that has steps to perform a specific task, but do not introduce the list with a stem sentence, readers might be misled, confused, misinformed, etc.

Now, let’s see the following example:

1. Use one of the following methods to start the Manage Information Catalog wizard:

* From the Windows desktop, click Start > IBM DB2 > Set-up Tools > Manage Information Catalog wizard.
* At a command prompt, enter db2iccwz.

The Manage Information Catalog wizard opens.

2. Select the Migrate metadata from an existing information catalog option.

3. Enter the required information on each page of the wizard and click Finish.

To me, it is apparent this is a procedure for migrating your data from an existing catalog to a new one. To my users, who are undoubtedly smarter than me because they are database administrators [audience, audience], it is very apparent that this is a procedure for migrating data from an old catalog to new; my users just do not need a stem sentence that goes:

To migrate metadata from an existing information catalog:

The title of the topic would, in any case, always have an indication of what is contained in the topic. The stem sentence adds nothing of value to the content except increasing the word count.

However, I have also come across procedures where, if a stem sentence were to be absent, important information would be missing. Here is an example:

The following steps are needed only if you overrode the default options when you installed the product.

The end result – I leave out stem sentences if I think there’s no value add in having them.

Leave the comparatives and the adverbs alone

I am in complete agreement. Whether an application is quickly installed, easier to use, and fastest in terms of response time is a conclusion best left to the user to arrive at. Technical writers are supposed to report facts, not hand out value judgements.

Computers (and computer applications) do not possess human characteristics, so, do not anthropomorphise them

I agree.
Did I hear someone say, " A piece of software does guide, control, direct my actions. Microsoft Excel lets me create spreadsheets but it does not let me create documents. An umbrella shields me from rain; a car gets me from point A to point B. It’s perfectly okay to anthropomorphise."

Picture source: http://www.wpclipart.com/cartoon/animals/fish/fish_with_umbrella_cartoon.png.html

I disagree with this line of reasoning. When someone says, "The umbrella shields me from rain", that is not anthropomorphism. That’s just someone using a verb correctly because that is indeed what an umbrella does – it shields people from rain. That is an action, not a human characteristic. Now, if someone were to say, "My brave umbrella valiantly tries to shield me from rain but fails", now that, my friend, is anthropomorphism because the umbrella has become possessed of the human characteristic of braveness (and chivalry, perchance).

Me? I let my software detect conflicts and resolve them but I do not expect it to be remorseful when it crashes my desktop.

A procedure should not have more than 7 steps
If anything takes more than 7 steps, says the stricture, break the procedure up into smaller logical pieces. I am guessing this comes from the assumption that readers have short attention spans. I said "guessing" because though I’ve been told there are studies that prove a decrease in comprehension levels after Step 7, I am inclined to believe if someone’s life depended on it, that person would read even War and Peace from cover to cover.

That said, I do try to keep my procedures as short as possible. But, sometimes, the products we write for do have procedures that cannot be fitted into the 7-step-frame. For example, can the instructions to install a rack-mounted server system really be covered in 7 steps? Really?

Conclusion
So, is the cow holy? Well, it depends.

[A slightly different version of this blog post was published in STC India's magazine INDUS.]

DITA tools - 4 (Authoring)

2010-09-04T21:44:00.004+05:30

I've had quite a few of my friends say, "Well, yes, we can do the information typing and we also totally get the semantic tagging concept of DITA but when we get down to actually writing in DITA, it is a bit of a hassle trying to remember all the tag names and where they are allowed. Is there a free WYSISYG editor for all this?"

In a previous blog post I had mentioned one such DITA authoring tool. In this blog post, I will talk about another.

The Serna XML Editor has a free edition that I've been using the past couple of weeks to do some personal stuff in DITA. For DITA authoring, I really like it and for the following reasons:

It comes bundled with the DITA open toolkit. I don't have to download and install the OT separately.
It also has DocBook (which is next on my personal ToDo list).
Its validators will not let you insert a DITA tag at a place where the tag is not allowed. You will be shown a list of allowable tags, with hovertext for each tag.

To see a larger image, click on the image
It lets you define the attributes of any element through an element-specific wizard page.

To see a larger image, click on the image
It lets you drag and drop elements. This is something we (writers) take for granted in our word-processing software but not many free XML editors have this feature.
It is WYSIWYG - not only in terms of DITA tags but also for output previews. To my knowledge, no other free XML editor gives a preview of the output.

To see a larger image, click on the image
It comes bundled with a transform engine (that's how it has the inbuilt output preview feature). This means you don't need a separate software for running the transforms. You do, however, need the JRE (if you want to publish to XHTML) and FOP (if you want to publish to PDF) - both of which are free to download and easy to install

The Syntext Serna Free XML Editor can be downloaded from http://www.syntext.com/products/serna-free/.

Some of the 'cons' that I've noticed thus far (I am not sure if these are a restriction for the free edition):

The glossary specialisation, though supported, does not result in transformed XHTML files.
Bookmaps, though supported, don't get transformed.

Writing in DITA - Tips #4 to 10

2010-05-13T21:02:00.003+05:30

A verbose version of these tips was published in the Mar-Apr 2010 issue of STC India's newsletter, INDUS, as DITA writing tips.

To conref dissimilar elements, wrap the source text in <ph>
To prevent all topics of a <reltable> row from linking back to each other, use the 'linking' attribute of <topicref;
To include pretty much anything in a <step>, insert an <info>
To preserve the formatting of a copy-pasted text snippet, use <pre>
To have topics show different titles in different scenarios, use <titlealts>
To caption images, use <fig> as container for <image>
To have a slightly longer <shortdesc>, put it in an <abstract>

To conref dissimilar elements, wrap the source text in <ph>

DITA is about content reuse - with a rider. Only like can call like. I cannot, for example, reuse a <step> as an <li> - if I want to reuse the text of a <step>, I can conref it only from another <step>. This becomes a bit of a hassle - say, I have written something in a <shortdesc> in a concept topic that makes perfect sense as the <context> of a task topic, how do I conref it? By using the <ph> tag.

To prevent all topics of a relationship table row from linking back to each other, use the 'linking' attribute of the <topicref> element

The relationship tables in DITA are an extremely useful tool for maintaining, at a single point, the linking between all topics in a book. Each row in the table represents a discrete relationship and all files in a row link back to each other. But sometimes I end up with more links than I really want. To prevent that, I qualify the <topicref> tags with either a sourceonly attribute or a targetonly attribute. When a <topicref> has a sourceonly attribute, a link is generated to the target topic only in the source topic; when it's targetonly, a link is generated to the source topic only in the target topic.

To include pretty much anything in a <step> tag, use an <info> tag

When describing procedures, sometimes it becomes necessary to include things such as pictures, code snippets, explanatory notes, and so on. But a <step> tag can contain only a <cmd> tag and then a bunch of other tags that are pretty useless for pictures, notes, and code. The workaround is to insert an <info> tag after the closing <cmd>; an <info> tag can contain pretty much anything.

To preserve the formatting of a copy-pasted text snippet, use <pre>

Because DITA is XML, anything enclosed within < > is interpreted as a tag. So how do I include, for example, a code snippet that contais angular brackets? I wrap the text in a <pre> tag, just like I'd have done if I were writing it in HTML.

To have the topic show different titles in different scenarios, use <titlealts>

I use <titlealts>, with which I can specify two additional titles: a <navtitle>, which shows up in the ToC pane, and a <searchtitle>, which shows up in the search results page. I make these two titles slightly more verbose than the actual page title, so that they make sense even when seen outside the context of the page content. In the absence of a <titlealts> tag, the title displayed in the ToC and in the search result page defaults to what's contained in the <title> tag.

To caption images, use <fig> as container for <image>

The easiest way to put an image in a topic is by using an <image> tag. But, according to the DITA language specification, an <image> tag cannot contain anything other than alt text. How do I caption my images? By wrapping the <image> tag in a <fig> tag, which can contain not only a <title> tag but a host of other useful ones such as <desc>, <note>, and <codeblock>.

To have a slightly longer <shortdesc>, put it in an <abstract>

The <shortdesc> element is what I use for writing the "click-through text" for the topic - the text that shows up in search results and in hovertext for links. Mostly, my short descriptions contain 2-3 sentences that sum up the topic. But sometimes, just sometimes, I feel the need to write a longer short description. I'd still like to retain the shorter short description as the "pull text", but what if I want to add another two sentences and want to have them all in that section itself - the first section on a page - instead of carrying the extra sentences over to the body of the topic (where they'll probably have to reside after a <prereq> and, thus, lose all sense of connect)? In such a case, I use an <abstract> tag

DITA 1.2 - New elements

2010-05-09T20:59:00.003+05:30

The DITA language specification v1.2 introduces two new task elements: <steps-informal> and <stepsection>.
The <steps-informal> element is for describing procedural information that is otherwise not normally described as a step. The <stepsection> is for giving explanatory information before a step. It is contained within the <steps> element and can be placed betweeen two <step> elements; the output of the content of a <stepsection> will not contain a bullet or a number.

When should I use the <steps-informal> and <stepsection> elements

<steps-informal>: The v1.2 language specifications haven't yet included an example of the <steps-informal> element so I am still a bit unclear about how and when to use it.
<stepsection>: If I am using DITA v1.1 and need to give some info before a step, the only way I could do that was insert an <info> in the previous step. With <stepsection>, this problem is resolved. Here's an example (taken from the v1.2 lang specs doc):

<steps>
  <step><cmd>Get out a bowl</cmd></step>
  <stepsection>The next two steps are very important!</stepsection>
  <step><cmd>Put on safety gloves</cmd></step>
  <step><cmd>Put on goggles</cmd></step>
  <step><cmd>Pour milk and cereal into the bowl</cmd></step>
</steps>

Related information

With v1.2, a <step> can have an <note> before the <cmd>.

DITA 1.2 - New elements

2010-05-07T22:00:00.007+05:30

The DITA language specification v1.2 introduces two new topic elements: <bodydiv> and <sectiondiv>.
The <bodydiv> element is intended to be used as a grouping element for containing logical blocks of info that otherwise do not need either a title or a separate topic. It can be placed only within a <body> or within another <bodydiv>.
The <sectiondiv> element is similar to the <bodydiv> element except that it has more container elements - it can be placed within a <section>, <sectiondiv>, and a bunch of other tags depending upon the topic type.

Why and when should I use <bodydiv> and <sectiondiv>

If I want to reuse a whole group of info somewhere else, these two tags are handy. Not that such reuse couldn't have been done otherwise, but then, these tags can, for example, contain several <p> elements, some lists, some images...it's almost like being able to reuse an information chunk instead of individual tags. Without being actual formal topics, these tags behave like topics.

Related information

The <concept> topic type also has a new element in v1.2 that's similar to <bodydiv> and <sectiondiv>. It's called <conbodydiv>.

History of <topic> elements

Here's a list of the various topic elements from v 1.0 to 1.2:

DITA 1.0	DITA 1.1	DITA 1.2
dita	-	-
topic	topic	topic
title	title	title
titlealts	titlealts	titlealts
navtitle	navtitle	navtitle
searchtitle	searchtitle	searchtitle
-	abstract	abstract
shortdesc	shortdesc	shortdesc
body	body	body
-	-	bodydiv
section	section	section
-	-	sectiondiv
example	example	example
related-links	related-links	related-links

Writing in DITA - Tip # 3

2010-04-09T19:34:00.005+05:30

While authoring, I often need to refer to that specific directory, that particular URL, this specific file which resides in this specific directory. As the software development cycle progresses, names change (and how). By the time people are ready for bit freeze, I am out of my mind worrying if all the specific references I put in your doc are updated (specific references are more "consumable" by a user). But if I've had the time to plan, I'd have probably envisaged such a scenario and prepared myself. How? I give here two alternatives (there could be more but I don't know of them yet). And, because I am making a case for Alternative 2, I'll shoot down each of the examples that I give for Alternative 1.

Alternative 1

Do not use specifics. Talk in generic terms. Examples:

From the Sun website, download the latest version of the Java Development Toolkit.
Problem: For all you know, Sun might be acquired by Moon, and the JDK be renamed to Lunar NetBeams.
In the installation directory of the software application, look for a file with a name that has a suffix that correspond to the product acronym as listed in the Offical Acronyms page of the software application.
problem: Which software application? You said Package A was prerequisite for Package B so I downloaded both from your website and installed them and they seem to be installed in the same directory - the directory name is the name of your company. Which subdirectory of the installation directory? There are no files in the main directory. Where is the Acronyms page? The first three hits in Google lead me to pages not maintained by your company.

Alternative 2

Use the conref facility provided by DITA.
DITA is about content reuse. We might as well rephrase that to say, "DITA is about reducing maintenance overheads". (<aside>The first sentence talks about a feature. The second about a benefit. Users look for benefits (what's in it for me), not features. Am a bit puzzled why so many techcomm people keep using the first sentence without, ah, repurposing it for the target audience.</aside>)

This is how I do it: I maintain a separate file called in which I have a bunch of text that I think are of a variable nature. Each chunk of reusable text is wrapped in a <ph> element and given an ID. Like this:

Then, in the main files, I just conref these <ph> chunks. The text comes out looking like this:

DITA tools - 3 (Transforming)

2010-03-24T00:30:00.002+05:30

To transform dita files to a publishable output, such as XHTML or PDF, we need to run ANT builds, and we do it through the DOS command line. Another option is to use a GUI. I find the WinAntEchidna GUI, developed by HyperText, to be very handy.

The first time that you use WinAntEchidna, it asks you for the installation directory of the DITA OT (this, like all parameters, can be changed any time). Thereafter, every time you run WinAntEchidna, all you need to do is specify your ditamap file, your output folder, and your output type.

WinAntEchidna can be downloaded from http://sourceforge.net/projects/winant-echidna/.

Quick and rude guide to DITA OT installation

2010-03-22T20:33:00.008+05:30

The install guide that comes with the DITA OT package is good (really, no sarcasm) but it sometimes assumes I am more of a techie than I really am. Last week, I changed my computer. It was while setting up my DITA environment that I remembered again that if I just follow these instructions to the T (see picture), I am more than likely to stumble.

So, I am writing up this blog post as a note to (i) myself, should I need to do this all over again (ii) everyone of you who wants to set up a DITA environment with minimal fuss. (<aside>I know; "minimal" is subjective.</aside>)

I use a Windows machine; these instructions are for a Windows setup (64-bit).

Download JDK. The latest version is JDK 6 Update 18 and can be downloaded from http://java.sun.com/javase/downloads/index.jsp. The file I downloaded is called jdk-6u18-windows-i586.exe.
Install JDK to a directory of your choice. To do so, double-click the jdk-6u18-windows-i586.exe file and follow the onscreen instructions. Stick to the default options. For the remaining part of this procedure, let's assume the JDK installation directory is C:\Program Files (x86)\Java\jdk1.6.0_18.
Download HTML Help Workshop. The file is called htmlhelp.exe and can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en.
Install HTML Help Workshop. To do so, double-click the htmlhelp.exe file and follow the onscreen instructions. Stick to the default options.
Download the full DITA OT package. The latest stable version is 1.5 and can be downloaded from http://sourceforge.net/projects/dita-ot. The file I downloaded is called DITA-OT1.5.1_full_easy_install_bin.zip.
Extract the contents of the DITA OT package to any directory of your choice. For the remaining part of this proceudre, let's assume this directory to be C:\Work_Area\DITA.
In the C:\Work_Area\DITA directory, look for a file called startcmd.bat, and double-click it.
In the command line window that opens, set the JAVA_HOME environment variable by running the following command: set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.6.0_18
In the same command line window, test your DITA OT installation by running the following command (which is an ANT command for transforming DITA files): ant samples.web -f build_demo.xml Wait for the command to get over.
Return to Windows Explorer and, in the C:\Work_Area\DITA directory, look for a folder called out. This folder was created as a result of the previous step and contains the transformed files. If you cannot find this folder, something went wrong with the installation :-(

Notes for subsequent transforms: Set the Java environment variables every time you run an ANT build, and do it from the directory where the ANT build is being run.

Related posts
Now that DITA OT is installed, you might want to get yourself an authoring tool? See this blogpost: DITA authoring tool.
Next, you might want to run your transforms, no, not through the command line, but through a GUI? My next blog post is about such a transform tool: DITA tools - 3 (Publishing).

Post script
The procedure I wrote contains several inline links, and references to specific software versions and local directories. As any writer knows, these are maintenance headaches. Whether docs can (or, should) really have such specific info, and, if yes, how to include such info with minimal maintenance overheads is explored in this blog post: Writing in DITA - Tip #3.

Writing in DITA - Tip #1 alternate solution

2010-03-18T23:06:00.003+05:30

The problem statement is this: Cannot put link text inside <xref>.

An alternate solution is here:

Cartoon created with http://www.makebeliefscomix.com.

Writing in DITA - Tip #2

2010-03-17T21:42:00.004+05:30

You are writing a procedure. You are, therefore, using <steps> for your list of actions that your reader needs to follow to complete the task. You have in mind something like this:

Because DITA tags are semantic, you want to enclose db2iauto -on <instance name> within a <codeblock> tag. But you hit a roadblock. You cannot include a <codeblock> tag within a <step> tag, says the DITA language specification.

What do you do now?
Insert an <info> tag after the mandatory <cmd> tag in the <step> tag. Then, insert <codeblock> within the <info> tag.
The <info> tag is pretty useful - it can contain paragraphs, lists, notes, images, ...

Writing in DITA - Tip #1

2010-03-16T16:38:00.011+05:30

Problem statement

Theoretically, the <xref> tag can contain plain text. It must therefore be possible to write something like:

<xref format="html"
href="http://publib.boulder.ibm.com/infocenter/c8bi/v8r4m0/topic/com.ibm.swg.im.cognos.ug_fm.8.4.0.doc/ug_fm_id21834Troubleshooting.html#Troubleshooting" scope="external">Troubleshooting guide</xref>

The authoring tool we use at work (Arbortext Editor) very decidedly does not think so.

So, the resulting output looks, er, ugly.

Workaround

Step 1: Insert a <desc> tag inside the <xref> tag, type something within the <desc> tag (it shows up as hovertext in transformed output), and then type something just outside the <desc> tag but still within the <xref> tag. Like this:

Step 2 (optional): Delete the <desc> tag.
Step result

Musings

I am fairly sure the problem is not a DITA bug but an Arbortext Editor bug. Anyone seen anything similar?

Post script,2 days after original post

See an alternate solution here.

Another post script, 20 days after the original post

The Arbortext people found this blog post and offered to help but by that time I had already found a solution. I am impressed by their follow-up - they are really trying to keep track of user pain points and minimising the attendant frustration. Thank you Arbortext (and Liz Fraley).
I'm still not sure, though, if it's not an Arbortext bug. The error message box is captioned "Arbortext..." and it has a bug number. The problem was I couldn't find a list of error messages (and possible resolutions) in the Arbortext help. Per my understanding, the problem seems to be - text selected within an xref tag cannot be overwritten; it can be removed only if it is not selected AND some other text is typed in AND the "generate referenced text" button clicked again. Maybe it's not a bug. But as far as I know, a standard method of deleting text is by overwriting it. Maybe an error message section in the help docs would help?

DITA and DITA-OT

2010-03-04T20:47:00.010+05:30

My attempt to answer a question that keeps coming my way at regular intervals: isn't DITA-OT the same as DITA?
Short answer: No. Longer answer: Read on.

	DITA	DITA-OT
What is the full form	Darwin Information Type Architecture	DITA Open Toolkit
What is it	A standard. An XML-based architecture for authoring, producing, and delivering technical information	A set of Java-based, open-source tools for processing DITA files
What is the latest stable version	1.1	1.5
Where is it	OASIS DITA Technical Committee	Sourceforge
Who owns it	OASIS DITA Technical Committee	Err, nobody. It's an open-source implementation licenced under CPL 1.0 and Apache Licence v2.0
When's the next update	1.2, under development since 2007 (track what's happening)	1.5.1, planned as a point release for DITA 1.2 and to coincide with the DITA 1.2 release

Help and its Usability

2010-03-01T23:46:00.002+05:30

A verbose version of this wishlist was published in the Jan-Feb 2010 issue of STC India's newsletter INDUS.

What if my Help was not at all like the Help as we usually see it?

What if every menu option had a tiny Help button with a hovertext that tells me the consequences of a click-through.

What if there was no ToC? What if, instead of a tree of topics, I am shown only one topic? The topic that I reached by clicking the tiny Help button on the options on the menu bar?

What if every Help topic helps me orient myself with a You-Are-Here clickable flow-diagram.

What if all UI fields had examples?

What if the Help button on a UI field opened for me a page that shows the results of a predefined search – a search based on the UI screen I was at (and related to the task I was doing) when I clicked the question mark?

What if the UI had embedded cheat sheets that guide me along.

What if I had On-the-spot troubleshooting where an error message, instead of telling me what went wrong, pops up a wizard with which I can do that which should have been done in the first instance?

What if wishes were horses? Why, I'd gallop along on my tasks with nary a roadblock in sight.

DITA tools - 2 (Authoring)

2010-02-27T23:28:00.009+05:30

I am very comfortable with using Notepad to write in DITA. But there are times when I forget if a particular DITA tag can be used at a particular place. For example, I regularly forget if <prereq> should precede <context> or follow. At such times, an XML editor that also validates your tags as you type comes in handy.

XMLmind XML Editor is one such tool and comes bundled with the DITA DTDs and schemas. Its personal edition is free to use for non-commercial purposes and is, thus, great if you want a WYSIWYG DITA editor for your learning and other personal stuff. With it, you can visually insert DITA tags, specify the attributes of the DITA elements, type your content, and validate your file (the file is valid by default because you'll be unable to insert invalid tags) - everything that an XML editor generally does.

To see a bigger picture, click the picture

The XML editor can be downloaded from http://www.xmlmind.com/xmleditor/persoedition.html.

DITA tools - 1 (Planning)

2010-02-25T19:44:00.013+05:30

Disclaimer: IBM is my employer.  But this blog post is mine own. Entirely.

The IBM Information Architecture Workbench is an Eclipse-based freeware that I find marvellously handy for organising my thoughts and then committing those thoughts to DITA files. With it, I can model my ditamaps, generate DITA stub files* for the ditamap nodes, and edit the DITA files. Plus, if I draw a line from File A to File B, it gets registered in the ditamap's relationship table. All pretty neat and clean. It shows me, visually, how my topics are arranged in my book (and lets me move around files with a drag-and-drop action). It also shows me orphan files - those nodes that I created but did not link anywhere. And, I can edit the DITA attributes very easily in the Properties view.

To see a larger picture, click on the picture

One can use this workbench for other assorted activities like Hierarchial Task Analysis diagrams and Role and Goal models but I confess I haven't been there yet. I use it as just an authoring tool. The workbench also has an inbuilt client for CVS, so I can have a multi-author scenario for my files too.

The workbench can be downloaded from https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?lang=en_US&source=swg-iiaw. To download, you need an IBM ID. Anyone can create an IBM ID for oneself - all that's asked is an email address and (I think - have forgotten) a name.

*Stub file: A stub file is a DITA topic file created for each of the nodes in the ditamap. Depending on the kind of file you specified while creating the node, the stub file has basic DITA tags for that topic type. The stub files can be opened with the workbench text editor, and edited like any other file. Thus, the workbench doubles up as an authoring software.

Quick and rude guide to DITA - Part 3 of 3

2010-02-21T19:41:00.025+05:30

In Part 2 of this series, you created some DITA files. If you are a technical writer working in an organisation that's already using DITA for authoring, you wouldn't really need to bother with transforms and outputs - there will already be a system in place with which you can do a click-and-generate-output (well, almost). You need not, therefore, really bother yourself with this part (Part 3, last of the series) unless you're really eager to see how your DITA files look in HTML. If that's the case, read on.

In your root directory, create a subdirectory named Sample.
In the Sample directory, create three subdirectories, and name them ant_scripts, topics, and out.
In the Sample > topics directory, put your DITA files. Your DITA files must have dita as the file extension.
In the Sample directory, put your ditamap file. The file extension of your ditamap file must be ditamap. If needed, edit the ditamap file to correct the filepath reference of your dita files (because now they reside one directory lower than your ditamap).
Download and install the DITA Open Toolkit (DITA-OT1.4.2.1_full_easy_install_bin.zip).
Download and install the DITA sample garage files (ditaotug131-18042007-garage.zip).
Go to the DITA sample garage installation directory and thence to the ant_scripts subdirectory. Look for a file called garage_hierarchy_all.xml, and copy it to your Sample > ant_scripts directory. Rename the copied file to build.xml.
Edit this build.xml file as follows:
- Replace all instances of DITASAMPLE_GARAGE_OUTPUT with out.
- Replace all instances of hierarchy.ditamap with the name of your ditamap file.
Go to the DITA OT installation directory, look for a file called startcmd.bat, and double-click the file.
At the DOS command prompt, run the following command: ant -f build.xml dits2xhtml
If your build.xml file is in a different directory than the DITA OT installation directory, specify the full path of the build.xml file. Your DITA files start getting transformed to XHTML and placed in the out directory you specified in the build.xml file. Wait for the command to complete.
Quit the DOS prompt, return to Windows Explorer, and go to the out directory. The index.html file is the landing page for all your DITA files.

That's it. You wrote some stuff in DITA, and created an HTML output. You're DITA ready :)

But wait! There's actually an easier option to convert your files to HTML without having to go through the 11 steps I listed. To create your transforms with just one single step, one single command at the DOS prompt, see this excellent article: http://www.ibm.com/developerworks/library/x-tipditajavacmd.html.

Quick and rude guide to DITA - Intermission

2010-02-10T14:48:00.012+05:30

<task>
<title>Celebrating the World Umbrella Day</title>

<shortdesc>To celebrate the World Umbrella Day, which, according to radio reports, falls on Feb 10, 2010, get yourself an umbrella and follow the steps given in this topic.</shortdesc>

<taskbody>
<prereq>
<ul>
<li>Obtain an umbrella.</li>
<li>Navigate to a sufficiently windy place. A place that measures 5 or more on the WindScale is sufficient for the purpose of this task.</li>
</ul>
<prereq>

<context>
<note outputclass="caution">Following the steps listed below might make you lose your possessions including, but not limited to, your umbrella.</note>
</context>

<steps>
<step><cmd>Stand on firm ground and open your umbrella.</cmd></step>
<step><cmd>Watch your umbrella fly away. Simultaneously, sing at the top of your voice <userinput>Chhatri udi, ud ke chali</userinput></cmd></step>
</steps>

<postreq>Acquire a new umbrella.</postreq>
</taskbody>

<related-links>
<link><linktext>http://writing-technical.blogspot.com/2010/01/quick-and-rude-guide-to-dita-part-1.html</linktext></link>
<link><linktext>http://writing-technical.blogspot.com/2010/01/quick-and-rude-guide-to-dita-part-2.html</linktext></link>
</related-links>

<task>

Quick and rude guide to DITA - Part 2 of 3

2010-01-30T23:50:00.022+05:30

In Part 1 of this series, I said DITA was about chunks and tags, and asked you to look at this user guide. My aim was to get you thinking in terms of topic types ("Hey, this table is a reference, what's it doing in the middle of a task topic"). In this post, I'll talk of writing your first DITA topic.

DITA is XML, so you can use pretty much any text editor to write in DITA. Here's an example:

(to see a larger picture, click the picture)

Because DITA is nothing but XML, it has its own DTDs, schemas, XSLTs, etc. The DTD used in this example is the one distributed through the DITA Open Toolkit, about which we'll talk of a little later. The tags used in this example are the ones we saw here.

So, we have a DITA file. If we're writing a "manual", we will in fact have several such files. How do we organise the files into a coherent whole? We use ditamaps. A ditamap is a collection of DITA files, ordered and nested in the manner that you want. It's a tree with nodes and sub-nodes, a generated reference file where the topic files are not embedded, only called. A ditamap could look like this:

(to see a larger picture, click the picture)

Each topic is called through a <topicref> element. One <topicref> can contain many others (see the highlighted portion).

Would you want to try your hand at writing a small manual, reading which a user can download, install, and use XML Notepad 2007 of Microsoft Windows?

Quick and rude guide to DITA - Part 1 of 3

2010-01-16T19:41:00.020+05:30

First, a DITA overview. DITA is an architecture. It is a collection of design principles that:
* Is inclined heavily towards self-sufficient information modules
* Lets its basics to be inherited into derived classes
* Borrows its tags from HTML and XHTML

To write in DITA, you need two things:
(i) Know how to think in chunks. Each topic you write must answer one - and only one - of these questions: What is this? How does it work? What should I do to make this work?
(ii) Know what tag to use where. DITA tags are XML tags, governed by the DITA DTDs and schemas.

Chunking
To keep matters simple, we'll look only at three kinds of topics: concept, task, and reference. Here's more about them (to see a larger picture, click on the picture):

Tags
Here's a list of some of the more commonly used tags (to see a larger picture, click on the picture):

In the next blog post, we'll do a short DITA exercise. In the meantime, have a look at this user guide and begin thinking in chunks and tags... (Disambiguation: Read Kai's question - in the comments to this post - and my response to Kai.)

P.S. If you really need more information, here's some reading material about basic concepts and about tags.

Building a portfolio

2009-12-16T21:27:00.042+05:30

This is the text version of my presentation at the STC India annual conference at Bangalore last week. It is a long post.

What is a portfolio? Let's see what the Compact Oxford English Dictionary has to say.
That's four meanings but for this blog post, we're interested in #2. Just like a set is a collection of well-defined objects, a portfolio is a collection of objects intended to show your ability in the field of technical communication. But why is a portfolio needed in the first place? Well, for one, because job ads ask for it.
A portfolio shows writing and editing capabilities, ability to create different document types, and experience with tools of the trade. A portfolio is your business card - it plays a large role in determining whether you get that interview call.

Now, the question is - why do you need to create one? Don't you already have a portfolio? Here are three questions that I've been asked often, and my response to those questions.

Can’t I use samples from my present workplace?
Nope. We work for hire and the employer owns every piece of work that we produce in the course of our employment. Let's look at it from another angle: Let's for a moment assume you work in a car factory. You are on the shopfloor, along with your colleagues, building a car. When the car's ready for delivery, can you drive it away and park it in your garage, claiming because you built it, you own it?
We cannot use any of the work that we do at our workplace anywhere outside your workplace unless our employer tells us to. Or, permits us to.
Now, let’s face it – how many of us want to walk up to our manager and say, "May I use this Demo, that I created, as an item in my portfolio?"
If I remove all proprietary information from the pieces, can I use them?
Nope. Think back to the car example. Assume that the car is factory-painted yellow and has a dancing fairy affixed on its bonnet. So, if you spray-paint the car green, and throw away the fairy, is the car yours? Not at all. Not only does it still belong to your employer, created at the employer's workplace using the employer's resources, it's now been tampered with without the employer's permission!
Can’t I send the URL of my blog as a sample of my writing?
Heck! Since when did a blog become a sample of technical writing? Anyone can write. Even poets can write. Let's assume John Keats has a blog. Instead of writing something like this (the "desired" format)
he would've written something like this:

When I have thoughts WordPerfect may cease to beI only have to press the CtrlF4 keyAnd behold my docs high-piled in charactryWithin Microsoft Word's own new domainHeld like rich garners the full ripen'd grainThat can be cut, copied, and pasted againTheir shadows, with the magic hand of chanceI only have at the Standard toolbar glanceFor selections to move on the page and danceOf the wide world I stand alone, and thinkAll it takes is a DELETE key, and dingMy words, all selected, to nothingness do sink

So, what do you do? This:

Arm yourselves with the required resources
Create a portfolio of writing samples that are relevant to the technical communication field
Showcase the portfolio to prospective employers

Let's look at these three points one by one.

Arm yourselves

Learn how to write technical documents. Unless you know how to write, you cannot write that which is to be written.
Learn how to write techdocs. About doing your research and gathering inputs. About what kind of information to include in your document and what information to leave out. Learn how to write in a structured manner. Learn about information chunking and how to categorise your material into conceptual, procedural, or reference documents and topics. Learn to visualise the kind of reader who would be reading your document and tailor your writing for that reader and that kind of audience. Become familiar with the basic documents that a technical writer is expected to work with, and learn about what goes into those documents – the purpose of those documents, the structure, the content. Before you actually begin to write, learn how to write.
Then, write. Review what you've written, correct your errors, write some more. And, get someone else to critique your writing. What should you be writing on? We'll come to that in a moment but in the meantime, use pen and paper and write (many companies administer their impromptu writing tests on pen and paper. Even today.)
Get ourselves a writer’s toolkit. See this list of free-to-download-and-free-to-use tools I've used myself. After you've made yourself a workbench with these – or similar – tools, familiarise yourself with them. You don't need to learn every feature and every little detail. It is sufficient if you know what all the tool can be used for, and if you know how to use it to do what you want to do.
After learning the tool, go back to your pen and paper writing samples, and redo them with these tools.
Work on some projects. See this list for suggestions on where to go looking for real-life projects outside your paid job. Why should you volunteer to be a technical writer for these projects? For one, it demonstrates your commitment to the profession, and your ability to work with teams that are geographically distributed. Also, it is a live, real-time, hands-on example of documenting a live, under-development project – and therefore, it demonstrates your ability to understand an application while it is still not complete, interact with coders and understand requirements and specifications, AND plan and deliver the kind of output that's best suited for the project.

Create a portfolio
Here are some suggestions of what can go into your portfolio.

A How-To procedure document
A specification, explaining how something should work
A quick-start guide
An installation guide
A reference book, like an API guide or a glossary

Reviewers like to see at least one example of an information type for a specific purpose and audience - for example, installation and administration guide, user guide, tutorials or learning material, multimedia. The tools you use for creating these samples is not important; what is important is how you analyze the needs of your audience and how you tailor your information to meet those needs.
If you are being interviewed for a junior level, do have a sample that has user instructions for a simple task.
If you are someone with a couple of years of experience, try to have a sample of an installation guide. In particular, a configuration guide.
If you’re someone who is more experienced, it might be a good idea to show that you can translate a use case document, SRS or FSD into user instructions. Your volunteer projects can contribute to all of the examples that I listed above. An appliance that you use at home lends itself very easily to a User manual. An activity that you taught someone in your family becomes material for a procedure topic or a tutorial. A roadblock when you were learning a tool can be turned into material for a troubleshooting guide or an FAQ. There are no limits, really. Just use your judgement and create the samples for your portfolio.

Showcase it
Now that you're ready with your portfolio, show it to the world.

Introduce each sample by giving some context. This is important because you would, in all probability, be showing an excerpt, not a complete piece. Mention the principles you used for creating the sample. This is important because they demonstrate your ability to figure out why you did what you did. Highlight some of the challenges you faced. State the constraints, and mention what could've been done to work around them or overcome them. Keep the introductions as short as possible.
Create a soft copy of your portfolio (burn it on a CD - not many employers are willing to risk using virus-philic pendrives) and carry it to your interview.
Constantly review, and add to your portfolio. Over time, weed out weaker samples. Samples should showcase the breadth of your experience and expertise. Like I mentioned earlier, for someone at a junior level, simple task topics are fine but as you gain experience, try tackling more complex topics and also other modes of delivering content. For a non-text example of Help, see this video.

You're now ready with your portfolio of samples.

List of tools

Content authoring tools: OpenOffice Writer, GoogleDocs

Image manipulation tools: IrfanView, GIMP

Publishing tools: Microsoft HTML Help Workshop, HelpMaker Help Authoring Tool

back

Pro bono projects

http://sourceforge.net/

http://contributing.openoffice.org/writing.html

http://www.gnu.org/doc/potentialauthors.html

Why a video sample? Because a large proportion of the population are visual learners.

back

Play play

2009-12-10T20:31:00.007+05:30

I made this crossword for the conference newsletter of STC India's annual conference that happened last week at Bangalore. Take a shot. I'll post the answers 3 days from today.

The crossword is not interactive, so you might want to take printouts... To see a bigger picture, click on the crossword.

To see a bigger picture, click on the clues.

Answers are here.

When the ToC spins out of control

2009-09-19T17:43:00.021+05:30

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

This post has a post script written about 45 days after the original post. And a second postscript almost six months from the original post date.

---------------------------------------------------------------
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 1 dated November 6, 2009
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 (from Post Script 1 response)
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]

Post script 2 dated March 10, 2010
Because the road map was such a success, we're toying with the idea of automating it - answer some questions about your deployment setup and get an on-the-fly custom install guide.
---------------------------------------------------------------

Bad docs rarely mean bad sales

2009-07-04T09:33:00.015+05:30

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.

Task flow - Analysed?

2009-05-16T16:09:00.011+05:30

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?

2009-05-10T16:17:00.023+05:30

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

2009-05-01T15:38:00.005+05:30

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

2009-04-12T22:53:00.007+05:30

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

2009-04-01T22:43:00.004+05:30

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

2009-02-26T09:34:00.006+05:30

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

2008-12-29T15:24:00.005+05:30

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

2008-12-20T21:39:00.006+05:30

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

2008-12-13T20:01:00.005+05:30

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

2008-12-06T21:25:00.010+05:30

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

2008-12-02T10:43:00.004+05:30

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

2008-12-01T00:14:00.001+05:30

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

2008-11-25T14:47:00.005+05:30

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

2008-11-21T22:50:00.009+05:30

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)

2008-10-11T23:04:00.006+05:30

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

2008-10-04T21:21:00.048+05:30

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

2008-10-01T20:01:00.002+05:30

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

2008-09-03T19:55:00.009+05:30

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

2008-08-15T23:20:00.000+05:30

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

2008-08-15T20:25:00.009+05:30

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)

2008-08-04T09:46:00.016+05:30

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:

Extract the source text from the image.
Create a duplicate image minus the text.
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

2008-07-09T17:00:00.000+05:30

"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

2008-06-10T13:20:00.003+05:30

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?

2008-06-03T22:26:00.002+05:30

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

2008-05-28T10:06:00.002+05:30

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

2008-04-29T17:37:00.003+05:30

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

2008-04-15T17:02:00.003+05:30

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

2008-04-06T13:03:00.004+05:30

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

2008-03-21T00:34:00.001+05:30

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

2008-02-24T15:36:00.003+05:30

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

2008-02-21T18:51:00.005+05:30

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

Translating Tagore

2007-12-05T22:21:00.002+05:30

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!

Support Cases and Documentation

2007-11-25T11:58:00.001+05:30

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.

The Story of a User Manual

2007-10-17T20:51:00.002+05:30

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.