Oh yeah! Here goes.

Before we begin, the previous para is a very substandard illustration of a fancy technique of writing fiction: stream of consciousness, where you write down your thoughts as they occur. Now why am I saying this? In my rude guide, I wrote

…you primarily write to achieve technical and subject-matter accuracy and clarity. Your readers and/or reviewers’ primarily concern is whether you’ve achieved that and not so much for that wicked turn of phrase that you’ve introduced in the second para in the Overview of the Megaphone Connector for JDBC (Heading 1)…in other words, writing in this case, is subservient to technology/subject matter.

And now, back to the “much water has flowed” bit I just mentioned. Over the past month, I was witness to a fascinating discussion the details of which I shall spare you. It was a discussion centered around the (lack of) very basics of writing. Which is why I thought it’s time to re-examine the “writing in this case, is subservient to technology/subject matter” statement.

Problems in most human endeavours–I love it when I sound lofty–can be overcome if you abide by three factors:

1. Solid grounding in the fundamentals
2. Common sense
3. A penchant for not taking things literally

I know I’m sounding like I’m on a high horse talking down to ordinary mortals but indulge me, please. There! I said please. In all sincerity, let’s see how these factors apply in our context:

1. Solid grounding in the fundamentals of language/writing: I never tire of saying this: Technical Writing = Technical + Writing, where writing should be second nature to you. At the very least, writing mustn’t be an effort for you. If you plan to learn the parts of speech, articles, elementary sentence construction, and voices on the job, you’re probably considering a wrong career choice. Like I said, technical writing is not for everyone. Writing is not an optional skill for a technical writer.
2. Common sense: Cannot be defined although the dictionary says it is “exhibiting native good judgment (adj)” and “sound practical judgment (n).” Quite good but nobody can ever say what the judgment in question really is–it is entirely situational. Which is why the world abounds with helpful examples of what common sense is. I hate to do this to you but if you were given a lemon and presented with some choices would you rather squeeze it on your neighbour’s open wound or make lemonade or use it with Tequila (ha!)? Answer carefully. In much the same way, common sense dictates that if it takes you 37 steps to document a feature, you’d rather talk to your project team and simplify the interface. And because we’re talking about writing, common sense tells you that it’s a mistake to use figures of speech in a technical document: You cannot retrieve your files if you permanently empty the Recycle Bin just like trash once taken away by the garbage van cannot be recovered.
3. A penchant for not taking things literally: This is really a variation of #2 above. So when I say “much water has flowed,” you must not conjure mental images of water flowing underneath a bridge or something. The same thing applies for “I’m on on a high horse.” I’m a technical writer, not a jockey, for God’s sake. And so, when I say “writing in this case, is subservient to technology/subject matter” it doesn’t mean you take it literally: it just means that I assume that you possess above-average writing skills (ref:#1 above) when you call yourself a technical writer. If you call yourself a surgeon, remember that at the least I don’t expect you to use a butcher’s knife for performing surgery on me.

Actually this entire post is an exercise in stating the obvious but I suppose I haven’t stated it in vain.

Tags: Advice, Basics, Commonsense, Documentation, Language, Random Stuff, Tech Writing, Technical Writing, Writers, Writing

Technical Writing is largely a thankless job. Nobody really reads the document that you took six months to write but when they read, the results can sometimes be as devastating as the loss of your job because of all things, they had to look at that sentence on page 243, which contained an erroneous instruction, which in turn screwed their entire HRMS system. Okay, I’m exaggerating but you get the point: you do you’re unnoticed but you don’t and you’re dead. The money might be good but there’s precious little to motivate you to stick to technical writing as a lifelong career.

And so let me offer some sanctimonious advice: don’t take a technical writing job if you don’t enjoy it. If you’re planning a career in technical writing, make sure you do lots of research. If you think you can become a technical writer because you love writing and/or you write well, think again. Or if you do jump in recklessly–which is good in some cases–test the waters for a couple of years, but get out the moment you begin to realize that for a week or slightly longer, you’ve been spending your nights weeping softly into your pillow with the certainty that you’ve to wet your pillow with your tears the following night. And don’t look at your peers in the same company or industry with acid-filled eyes and envious wonderment at how they seem to enjoy it so thoroughly and earn so much (yes!).

What is technical writing

At the very basics, you’re on your way to technical writing superstardom if you possess and sustain these qualities:

• A sense of explorative curiosity that prompts you to investigate how something works. You are compelled to figure out how it works by dismantling and reassembling it if required. You might necessarily not know–or are not interested in–how to actually build it, and that’s perfectly fine.
• A passion to explain this to other people–orally…well, verbally, or in writing.

In a way, a technical writer is like a teacher who doesn’t lecture to a class but disseminates his/her lectures in the written form. For our purposes, we’ll restrict this “something” to technology/software.

It’s actually quite easy to proclaim your “passion for technology” as loudly as possible but look what happens when that translates into a job routine. You need to be constantly abreast of whatever technology you’re in and learn how it is actually applied. What this means is endless reading of complex technical documents. Remember, you’re writing to make others understand. If your own understanding is less than near-perfect, chances are you’ll be hit by that page 243 bomb.

It’s also equally easy to proclaim your “lifelong love affair with writing” and your “exquisite felicity with the written word” but here’s the thing: you primarily write to achieve technical and subject-matter accuracy and clarity. Your readers and/or reviewers’ primarily concern is whether you’ve achieved that and not so much for that wicked turn of phrase that you’ve introduced in the second para in the Overview of the Megaphone Connector for JDBC (Heading 1).

In other words, writing in this case, is subservient to technology/subject matter. The more firmly this is embedded in your consciousness, the less you will crib about or feel distraught at the lack of respect/recognition/appreciation for your amazing literary acrobatics. However, this is not to argue in favour of below-average writing skills. Make sure you have adequate command over your noun/number agreement, subject-object relationships, dangling modifiers, split infinitives, and the rest. Here’s a small trick that usually works: if you think your sentence doesn’t sound right, it probably isn’t. Read it aloud and check how it sounds. You’ll be surprised how quickly you can fix it.

If you are an aspiring technical writer and if all of this sounds sufficiently threatening/boring/intimidating, stop reading now, and if you’re a technical writer who already hates his/her job, look for a different career.

If you want to read, on, here’s the instant-coffee guide to becoming a successful technical writer:

• Be very unafraid of the monotonous drudgery of reading specifications, technical documents, talking to people, fiddling with the product, writing, editing, and writing again.
• Your writing skills can be improved. The Internet is your best friend and I don’t believe in spoonfeeding.
• Prepare. Look at what your competitor has done with a similar product. Read that product’s literature. Play with it if it’s available to you. See how you can apply that knowledge to your own work.
• Read a lot outside your work or domain. You’ll be surprised what all you’ll learn.
• Do your homework before approaching your SME or engineer. Ask questions that make them think. This is the only way to earn respect.
• Approach documentation from a problem-solving perspective. It helps to recall how you solved a complex quadratic equation back in school or college.
• Have a sense of humour. Accept criticism with grace. If your document is erroneous, it’s not because you are inherently evil.
• Observe, and learn how the really good technical writers approach a task or problem. It’s really okay to imitate them–that’s how you learned how to speak in the first place.
• Write. Write. Write. Practice is still the key.

What technical writing is not

• A shortcut for a development/QA or whatever other position, which demands a different skillset.
• A “hobby” or something you do because you’re bored at home.
• Merely documenting procedures is NOT technical writing. Print this line and paste it at your desk or home or car or whatever other place so that you’re constantly reminded of it.
• Process adherence might get you a beer and biryani dinner from your QA/SQM team but your reader will still look for accuracy.
• Ditto for fonts and styles and style guides and templates and XML and DITA and the rest. These are mere aids. A crutch is not a substitute for walking.
• Going through salary surveys is only bound to produce lots of bile.

Like any profession or career, you need to invest the required amount of hard work and seriousness that technical writing demands. Technical writing is thankless. Your only reward is that unexplainable, relaxing satisfaction that you derive after a hearty meal or a good bout between the sheets. It’s not for everyone.

Technorati : Advice, Career, Technical Writer, Technical Writing, Writing
Del.icio.us : Advice, Career, Technical Writer, Technical Writing, Writing

Keeping the Past Alive is Rewarding

Have you ever-even for just one second-paused to actually trace the origins of the words-any word-you use in your writing or speaking life? Try it. It’s fun, instructive, and interesting.

If the previous paragraph has convinced you to trace the origins of words, congratulate me because I now successfully qualify for a membership in the (U.S) Democratic Party. I’ve now become a Democrat. The connection between the previous paragraph and my becoming a Democrat will be clear in a moment. At the time of the American Revolution, the word Democrat had the pejorative meaning that we associate with the word Demagogue today-”a politician, leader or person who panders to emotions and/or prejudice”. In just over 100 years, the word Democrat had shifted so much in meaning that it is now the name of one of the only two American political parties. But look at what has happened to Democrat’s “parent” word, Demagogue. It now means the opposite of what it originally meant: a popular leader.

If the previous paragraph has confused you, re-read it.

Now what has happened in both cases is a gradual change in the original meaning of the word. Technically, the study of such changes in the meaning-or evolution -of words over time, across cultures and geographies is known as Semantics.

But there’s another, more fundamental aspect to changes in the meaning of words. It is the origin of words, the root cause, or the culprit. In our example, the word Demagogue originates from the Greek demagogos, which means leader (demos) of the people (agogos). And the study of word origins is technically known as Etymology.

As writers, it pays to develop a healthy curiosity about the etymology of the words we use everyday. The “benefits” might not translate into a pay hike or promotion but it’ll help us become better writers eventually. A brief list of words we use in routine technical writing parlance hopefully spurs thinking in this direction.

Today, we typically use the word manual in the context of a written document (User Manual). This word was imported into English from the French word manual which, in turn, has its roots in the Latin manualis, meaning “fitted to the hand.” The root of manualis itself is derived from the Greek manus, which means “hand; strength; power over; armed force; handwriting.” These meanings have an echo even today in usages such as “manual labour” and “the user has to populate the fields manually (bah!).” In 1431, manual was used to mean “a service (Church ritual) book used by a priest.” Around 1533, this restricted definition transformed itself to mean “a concise handbook of any sort.” And viola! We have today the User manual, the Manual of Arms (military), a manual of mathematical tables, and so on.

While we’re talking about user manuals, let’s briefly dwell upon navigation. In very simple terms, to navigate is to find our way around something. Interestingly, the verb navigate came later than the noun navigation. This word has seen little change in meaning ever since it was first used in 1533, derived from the Latin navigationem, which means “to sail; sail over; go by sea; steer a ship.” Navigationem is itself derived from Navis meaning “ship.” Although the original meaning is still in vogue, navigation is used today in the sense of “finding or helping find something-a place, an object, a direction, or information.”

From navigation to navigation aids (no, not the acronym). More specifically: Index and Glossary.

The lexicon seems to be quite fond of Index,notperhaps because the lexicon is itself an index of sorts but because Index yields a huge heap of meanings. For our purposes, it is simply a navigation aid, an alphabetical listing of words accompanied by page numbers. And it is 611 years old with roots in the Latin Indicis, meaning “forefinger; pointer; sign; list.” Does the word Index Finger sound familiar? However, it is also derived from Indicare, which, literally, means “point out.” The word Indicate has its roots here. Sometime in 1580, English incorporated Latin phrases such as Index Nominum and Index expurgatorius to roughly give Index its current meaning. Index Nominum literally means an “Index of Names” while Index expurgatorius has a slightly tyrannical connotation. It literally means “specification of passages to be deleted from works otherwise permitted.” Post 1720, the usage of Index branched off in a hundred directions to variously mean “compile an index (of terms/words), refractive index, economic index,” and so on. For our purposes, we’ll simply to stick to generating Indexes for the documents we produce.

Sadly, the history of Glossary isn’t as colourful. For the most part it retains its original meaning from the Greek derivative, glossarion, which means “obsolete or foreign word.” Around 1400, the Latin gl?ssarium made its appearance in English to mean, “a difficult word requiring explanation.” Glossary was originally used in the plural as glossaries, and alternatively defined as a “collection of textual glosses.” Interestingly, the word glosses is itself derived from the (Middle High) German, glosen meaning “glow, or shine.” This has resonance in the modern usage of the lip gloss, a beauty aid. But it remains that glossary, which today means “a list of terms in a special subject, field, or area of usage, with accompanying definitions” hasn’t deviated much from its original usage.

I should’ve started this piece with this word but I chose to keep the best for the last. While a lot of words are rooted in antiquity, some are deleted forever, some fall to disuse, some are revived from disuse, and others still, are rescued from extinction. Interface is a good example of the last phenomenon.

Interface is derived by combining the prefix, Inter, with Face. It is a fairly “modern” word in some sense because it was coined around 1880-1885. It originally meant “a surface forming a common boundary, as between bodies or regions.” This word lay dormant for several decades until in the 1960s, the computer industry suddenly resuscitated it with the same sense of usage. Within the computer industry, interface generally means “a point of interaction between a computer and another system-like a printer or similar device.” However, its usage became pervasive quite rapidly and pretty soon, acquired newer usages. For instance, it is acceptable to use interface in the sense of denoting interaction between departments in a company or between areas of study: “we need to improve the interface between the documentation team and the HR team.” However, using interface as a verb is generally frowned upon because you have better substitutes in interact, deal, work, or cooperate. Whatever the usage debate, it’s clear that the world of words owes immense thanks to the computing world for rescuing this word from complete oblivion.

You obviously don’t expect me to write an Etymology dictionary here-two such comprehensive (searchable) dictionaries already exist online if you are interested: http://www.etymonline.com/index.php and http://dictionary.reference.com/browse/etymology. If you are a steadfast devotee of the printed material like me, I highly recommend the Oxford Dictionary of English Etymology, the Chambers Dictionary of Etymology, or the “lite” Barnhart Concise Dictionary of Etymology.

In the end, Etymology is tremendously rewarding not merely because it’s akin to a journey in history, or an enjoyable hobby but because its real value lies in the range of possibilities it offers us in the world of usage. It instructs us without preaching. It helps us to both break the lazy habit of using words frivolously–like cycling or swimming, you can never “forget” it once you’ve learnt it–and to become more effective writers.

If you are unconvinced still, check out the origins of bless, document, web, content, and search.

Technorati : English, Etymology, Language, Origins of Words, STC India, Words, Writing
Del.icio.us : English, Etymology, Language, Origins of Words, STC India, Words, Writing

Rebirth

Inside, the swirling wind swishes continuously
swooshing over my shut stony tomb
not powerful to slide its slab though
stiff enough to arouse the stirrings
of disturbance inside the confined hole.
Dark and bottomless, but I can’t see–
I’m stirring and trying to turn,
I wind my neck tight and kick,
a whiff unbeknown escapes in a gush,
a sudden dazzle greets the eyes I open and quickly close,
a rumble that begins in my belly becomes
a wail, and a shrill shriek—
multiple, painful simultaneous experiences like
gigantic waves that lash helpless pebbles who
gladly die this second in secure knowledge of
their rebirth in the next.

Tags: Original Poetry, Poem, Poetry, Rebirth

In my experience, Agile worked great for the developers and QA/testing folks but not as well for the UX and documentation folks. The primary reason was the constant flux in what emerged when an iteration ended. For example, if feature A was completed at the end of iteration 3, I’d document it the way it was looked (the user interface) and worked. However, in the planning meeting for iteration 4, somebody would point out that some UI element for feature A needed to change. Now I had to redo the documentation for the same feature in iteration 4. Additionally, in the same planning meeting, somebody else realized that a feature already completed in iteration 2 needed an enhancement. They’d put that as a task in iteration 4. I now had two repeat tasks. Add to this, every iteration typically had documentation reviews by these cross functional teams. Now, because each iteration typically lasted for 3 weeks at the maximum, the review task would be deferred to the next iteration. This meant I couldn’t mark my writing task as complete for the iteration although from a purely writing/authoring perspective, it was, indeed, complete. The resultant confusion for the writers bordered on chaos simply because it was too hard to keep track of what was going where. Kris explains this quite nicely:

I think when it comes to restructuring the workflow of a product to make it significantly better, executives need to understand there is a time for Agile, and a time to redesign, and redesign efforts take more in the range of 2-6 months to complete, in my experience. It all depends on how much is “surface” redesign, such as moving things around on the pages and creating a nicer look and feel vs. how much the deeper code has to be modified because features need to work completely differently than the developers designed them.

And nails it accurately here:

Do we need the internal motivation of a release every 4-6 weeks to make things happen? Customers don’t necessarily demand a release once a month, they just need bugs fixed and problematic features redesigned so they can perform their tasks better…Why do we have to release something once a month?

In other words, efforts to “quicken” the time to market shouldn’t compromise the “big picture” of the product. Ultimately, any product is the sum of its parts. The efforts should, really stay focussed on incrementally improving the product–in an Agile mode or no–than on making newer releases purely for its own sake, or worse, by a fear of the imaginary market monster.

In the end, the documentation folks were nicely frustrated. You can begin documenting a product if these conditions are met at the minimum:

• A reasonably stable feature set
• An interface that’s at least 80% frozen

Writing in our industry typically involves explaining things to other people. The better the writer understands what he is writing about, the less he has to rely on other folks for technical/product inputs. And to better understand, the writer needs to work real-time with the product that doesn’t change with every iteration. Ultimately, we solved the problem by beginning the actual writing work quite late in the game–that is, when we were reasonably sure that everything was pretty stable and changes would be minimal but we were present in the daily scrum, planning, and iteration-end meetings.

The biggest takeaway personally from Agile was how it offers a ruthlessly-close project tracking mechanism, and the scope it provides to build great professional relationships because you’re a small but tightly-knit team working really closely.

Tags: Agile, Agile in UX, Kris on Agile, Software Development, Technical Documentation, Technical Writing & Agile, Technology, Writing in an Agile Setup

Meanwhile, the BBC plans to do a documentary on Eliot’s private correspondence, which his widow Valerie has recently made public. A fascinating item therein is Eliot’s rejection of George Orwell’s classic, Animal Farm. This article calls it the “literary snub of the 20th century.” Eliot’s reasons for rejecting Animal Farm are equally fascinating.

When Orwell submitted his novel, an allegory on Stalin’s dictatorship, Eliot praised its “good writing” and “fundamental integrity”.

However, the book’s politics, at a time when Britain was allied with the Soviet Union against Hitler, were another matter.

“We have no conviction that this is the right point of view from which to criticise the political situation at the current time,” wrote Eliot, adding that he thought its “view, which I take to be generally Trotskyite, is not convincing”.

Eliot wrote: “After all, your pigs are far more intelligent than the other animals, and therefore the best qualified to run the farm – in fact there couldn’t have been an Animal Farm at all without them: so that what was needed (someone might argue) was not more communism but more public-spirited pigs.”

The original rejection letter discloses that Eliot was more concerned about Britain’s friendly relations with the USSR in the time of war. Here’s the revealing portion:

On the other hand, we have no conviction…that this is the right point of view from which to criticise the political situation at the present time. It is certainly the duty of any publishing firm, which pretends to other interests…than mere commerical prosperity, to publish books which go against the current of the moment. [Ed: Underlined]

Quite a giveaway, isn’t it? Thank God for Secker & Warburg, who ultimately published Animal Farm. We saw the truth fenced behind the real Animal Farm post Perestroika and Glasnost. Recall the Chief Pig who finally stands up and exercises his totalitarianism at the end of the novel?

Tags: Animal Farm, Eliot Rejected Animal Farm, English Novels, Fiction, George Orwell, Poets, T.S Eliot, Writers, Writing

Your poem, sir, is murky as the tide…
I think I understand it
But the answer eludes me.

Whether he had it in his mind when he wrote these lines I don’t know, but his last line compelled me to paste this poignant Sonnet from Shelley–in my opinion one of his best. I suspect Maugham was so impressed by this Sonnet that he named his very fine novel, The Painted Veil.

Lift not the painted veil which those who live

Call Life: though unreal shapes be pictured there,

And it but mimic all we would believe

With colours idly spread, — behind, lurk Fear

And Hope, twin Destinies; who ever weave

Their shadows, o’er the chasm, sightless and drear.

I knew one who had lifted it — he sought,

For his lost heart was tender, things to love,

But found them not, alas ! nor was there aught

The world contains, the which he could approve.

Through the unheeding many he did move,

A splendour among shadows, a bright blot

Upon this gloomy scene, a Spirit that strove

For truth, and like the Preacher found it not.

Tags: Lift not the Painted Veil, Literature, Poetry, Shelley’s Sonnet, Sonnet, Vittal

If a writer of prose knows enough about what he is writing about he may omit things that he knows and the reader, if the writer is writing truly enough, will have a feeling of those things as strongly as though the writer had stated them. The dignity of movement of the iceberg is due to only one-eighth of it being above water. The writer who omits things because he does not know them only makes hollow places in his writing.

He calls it the Iceberg Theory. You can use your own label to describe it but to attain just 50% of this level of clarity requires strength enough to move an iceberg using bare hands. I recall Paul Johnson’s description of Hemingway’s patiently-passionate ardour in crafting his work… "he ransacked entire dictionaries" and thesauri to find that one appropriate word.

PS: Currently (re)reading A Farwell to Arms. Will post a review soon. Kick my ass to remind me after a week or so.

And don’t miss Benjamin Franklin’s diary.

I’m going to bookmark this blog and add it to my blog roll.

Tags: Artists, Blog roll, Diary, Journal, Routine of Creative People, Writers

While I admit I’m given a bit to hyperbole, I have Emerson’s dictum about excesses and defects imprinted in my mind to actually implement my threat of unleashing unnecessary embellishment.

Thus, I actually think that a style guide is good.

But it is still a guide. It throws light on the path, it is not in itself the path. And which is where I narrate how I transformed my awe into a smile.

Without sounding too bitchy, pompous, or patronizing, I had this ex-colleague who fed on a diet of style guides. Microsoft Style for Technical Publications, Chicago Manual of Style, Sun whatisitcalled, Yale Style Manual, and assorted tomes gave this gentle soul the necessary proteins, carbs, starch, and fiber while I steadily grew weaker watching from the sidelines with open-mouthed awe. I realized painfully much later that this soul was learning to write using style guides. That cured me of the mindless affliction of over-reliance on style guides. It is like trying to learn how to solve a mathematical problem by referring to logarithmic tables.

At best a Style Guide gives you hints at proper usage, and dos and don’ts. All necessary, useful, and valuable. But it can’t predict the errors you might commit in your writing. That is your own burden and your own responsibility to lighten. And that task becomes easier if you read both widely and deeply, and read masters of prose, and practice.

While I’m still on the subject, do read the Economist’s Style Guide. It’s online, it’s free and contains plenty of sane advice. I specifically recommend memorizing the entire sections on tone and unnecessary words.

Best of all, read Hemingway.

Tags: Style Guide, Writing Advice, Language, Writing Well, Prose