I’m back after more than a month. Much water has flowed…okay chuck that! Grrr…what did I want to say? Oh well…I don’t know. I most definitely wanted to say something but it escapes me now…

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