Monday, August 3, 2009

How to Write Technically?

Writing is an art, no doubt. But anyone who can speak and write flawless English can become a good technical writer. Writing Technically isn't a very tough task. All it requires is understanding the content and reproducing it in carefully worded sentences.

Inspite of this, more often than not, most people involved in the software industry make a lot of mistakes while creating their functional and design documents. One of the reasons I believe why this happens is that software professionals do learn a lot of languages while at school earning their degrees, but they do miss out on learning how to write technically.

There are some basic points that one should adhere to while writing technically. I will be enumerating them below:

Use Active Voice and Present Tense.

Write Clear and Concise sentences.

Avoid technical jargon. While writing, try to keep the audience in mind at all times and you will avoid a lot of mistakes.

Write short sentences. Try and write 10 to 20 words in every sentence.

Try to document One Task in One Sentence.

Do not use acronyms that are not explained in the document.

Avoid ambigious sentences and large words.
Keep Short Paragraphs.

Use Bullets and Lists wherever possible.

Use Charts, Diagrams and Figures wherever possible.

Write Precisely, Accurately and very Carefully while defining terms.

Use Headings and Subheadings generously.

Repeat the same set of Formatting Guidelines and Words as often as possible in the document. This will ensure that the reader will soon become comfortable in reading your document and understand it better and faster.

Finally, Edit, Edit and Edit your document before you submit it.

We will learn and discuss all these topics in detail in the next few posts that I write.

No comments: