Writing Etiquettes

In this world of fame, knowledge, money, action...when everyone is targeting for bulls eye..trying to achieve even higher, larger, harder goals....
goals which are better than the best!!!!!!

In such a militant environment ( really sorry! for some of my readers might find it disparaging)....ok I take my words back.....though my mother says ("Abrasive words once out, can never be taken back, without causing some harm somewhere)..

In such a competitive environment ( this sounds much better :-)), it becomes imperative to hone our skills..

Best would be to ameliorate our technical skills, bcz of many reasons :

Brings you in the category of highly salaried class..
Your social status is enhanced, be it in ur company, ur juniors, ur cousins..technical magazines!!

But then this isn't that easy, especially for average brains like me (sorry Blogger, couldn't refrain myself from self-review))), specially when u don't want to put in that much effort as well...

There's a good side to it as well: we have an enormous scope to brighten our non-technical panoroma.

Last week, I was asked by my manager to attend some role based mandatory training on "Technical writing".I really liked the trng, and somehow instead of being virtually present, I attended the trng with avid interest, pinging the trainer and other trainees after every 5-10 minutes..

The trainer came up with some wonderful points, which I am gonna list below..
And if there is something u could really catch up with, plz pass on some good wishes for my trainer, for I really scratched her brain that day!!

1. Should an engineer be bothered about writing a good document???????

well, surprisingly, YES..lets quote some examples..

Take some product based companies : Adobe, Motorola, ST, Microsoft, Oracle..

They keep on publishing their installation manuals, user-guides..and who prepares them, ofcourse not the managers!

some services based companies: Aricent( well this is mine, and trust me I have improved a lot when it comes to writing tech docs.), Infosys, Cognizant, Hughes Systique, Wipro, UBS..here you have to write so many design docs, financial reports, survey analysis, requirement docs..

Some testing companies: AztecSoft (previously Disha technologies), TCS, Sun, Satyam, Accenture..there you have to write so many test plans, test scenarios, checklists, feature analysis..

2. Sequential V/s Flagship features:

Well, this is an open debate...No body in the trng fully agreed to the trnr's view point who believed in writing flagship featues first in the document, and not covering all the points sequentially...
e.g. suppose Sony Ericsson has come up with a new model again and it is giving a user manual along with the cell..
Then shd the user-manual come up with the explanation of flagship feature fst..which cld be say anything..sound quality, improved bass effect of their walkman series ..

or it shd be just a reference in the index..with the basic features coming fst like how to make a call, sending sms../mms..how to change themes/screen savers..

please pour in ur suggestions!!!!!

3. Domain Knowledge:

This is absolutely a must.Just imagine, a doctor is coming up with a white paper on say "Intrinsic benefits of eating Chavanprash". Writer has to be atleast at the same level as the reader..Always analyse ur audience ..it could vary from your client, who is a technical expert to a layman who is the end-user of ur application. Avoid giving basic information if the audience is at the same level.

Also , the information you provide should not be insufficient or incorrect.Always ensure to give references for the info you are not planning to cover but is in the scope of your doc.

Best remedy is to read your doc. again with a fresh mind in a day or 2.You will find so many areas to improve urself, this tip works more like new set of eyes reading it.

Never forget to get your doc. reviewed by a person more technically sound than you in that domain.Trust me, it really helps, opens up new areas to ponder upon..discard all ego/emotional/status barriers..and always try to follow this tip..

always think "WHY does the reader want to read this document!"


4. One-time OR a reference document:

Understand that you have to first prepare your reader for what's coming up.Don't we take an overview of any doc. fst before going into details..
Reader will always skip certain sections in the doc.

As an instance, suppose there is a doc. analysing a new feature, say which talks of transmitting Abis traffic on IP instead of conventional E1 lines..
The engineer as well as the manager will be interested in reading your doc.

Here you have to make sure, that you give references to various sections and not just describe everything in one go, so that readers can easily skip uninteresting topics, and at the same time you don't break the user's flow of understanding tasks/layers..

This is really important not to break the chain in reader's mind, otherwise the reader might start feeling irritated and when you present him/her a document next time, he/she might read your doc. with a pre-judiced mindset.

Say if it is a just one-time to be read doc., try to make it as catchy as possible... it is more or less a do or die situation..
But if it is a reference doc., say a doc which talks abt all the features of Boeing 777 aircraft, make it more systematic.
Always ensure to add a search engine in such a huge doc, where the search algorithm is such that it takes minimal time to access a particular attribute.

4. Avoid flowery language

Try to avoid gender-specific language wherever possible, though i must admit i have also used it in this post of mine!

And in the process of avoiding gender specific language, don't make it passive and never write in third person. l was atrociously puzzled when my trainer told me all these points in a go..and there I was, asking her to explain again an already elaborated instance :-D

Say you are explaining how to install a software using a CD, in such a case, always start with a verb; or to be precise, talk to your users.If plural is required , use "They". e.g. if xyz problem occurs, they can do this."

A spelling or grammatical mistake can play havoc to your doc's image and ultimately your image :-(((

Let me recall an interesting sentence passed by a professor, void of any punctuation.Let's see how both the genders deciphered it:

(F) Women: Without her, man is nothing.

(M) Woman without her man, is nothing.

Lastly, remember that an inappropriate style of writing will always make the reading boring or irritating, howsoever rich your content be..Well, to enhance it, you have to practise my friend..

I had come with a highly content rich user-guide last Dec, but guess what, my client did not even read it once because he did not like my template :-((

would like to quote a statement passed by none other than golf champ, Tiger Woods:

"No matter how good you get, you can always get better and that's the exciting part. "

5. Make MS word your friend not foe

Till date, MS word is the most feature-rich and user-friendly editor available. Try to learn and implement MS word tips as much as possible.

Learn how to fiddle around happily with tables, figures, cross-references, visio objects, track changes, header, footer, templates, toolbars, page-breaks, comments, embedded objects, bookmarks...

Try to understand why your doc. crashes at times..It could be because of memory-overload..Try to reduce resolution of visio objects in such a case.. Some companies have started using "doxygen"; it is a freeware tool to prevent excessively loaded doc. crash. This tool loads all the links only when clicked, that too in HTML format, unlike in MS word which by default loads all the embedded objects in one go.

Well, for all those who have managed to read till this point, here is a golden advice for you, given by my trainer:

"Write documents that you would like to read."

View My Stats