Many times, I ask myself a question that whether I am a “good” technical writer or a “bad” technical writer. I wonder what will be the definition of Good and bad technical writer. Being a technical writer, it is my job to put scientific and technical information into easily understandable language. I must empathize with my audience because it’s the audience who will appreciate my efforts, and not the client. Technical writing is a noble profession because it brings me closer to my audience, and allows me to convey only one meaning to the audiences. As a technical writer, I must not write in complex sentences filled with jargon and impressive words. When I started my first job as a technical writer, I had certain doubts in my mind such as whether this job will interest me or whether I will be able to earn enough money compared to my colleagues who earn a lot of money, or whether I would be able to communicate well with the programmers/developers. However, after having work for so long years as a technical writer, I have found an interest in this field. Now, I look back and realize what might have been the effective tips and techniques I got from my peers and managers to come at this level.
Tips and Techniques
Here are few technical writing tips/techniques to differentiate between good and bad writing.
- THINK BEFORE YOU WRITE: As a technical writer, it is essential that you must think before you start writing a document whether it is a user manual, a proposal, or any training manual. It is extremely important that you must analyze a product, process, and procedure that need to be documented. You must first understand yourself clearly what you are writing about. It is as good as saying that “Put yourselves in your audience’s shoes”. Think how your audience will react to the product or a system. As a technical writer, you must consider yourselves as an "advocate" for the user, which means that you explain a system clearly from the audience’s perspective, anticipating the questions and problems of an average user. In this way, you may even provide suggestions to the system or procedure while is in the design phase.
- KISS: The word "KISS" means, keep it simple and stupid. When I say simple and stupid, what am talking is to keep your document simple and you should not make use of drawn out and complex sentences in the document.
- “ALWAYS FOLLOW THE TASK-BASED METHODOLOGY”: I found this heading from a website, and found it interesting. Now, you must be wondering what this “task-based approach” is. Consider a scenario where you got a host of information from a team of developers / programmers, and now you begin your phase of writing. While you documenting (user manual, training manual, or any proposal document), you might confuse yourselves to put all these details and give a proper shape. Thus, you must follow a task-based approach which means that you should always break a particular concept into different tasks. This will affect in structuring your document properly. A task-based approach allows you to analyze what tasks will the audience of your document want to perform. This will help you to benefit in terms of organization, readability and usability of a document. For example, consider a scenario where you wish to write a user manual for MS Word. For this, you should first describe how to start MS Word, create a new document, print a document, and work with a document and save the document. However, some of the technical writer might not agree with me as they would feel that a structured-based approach will be definitely a good option to write a document. It is certainly not wrong to use a structured approach as it is also essential to include structural information if your document is to be complete. However, you must understand from the audience’s perspective that an audience always wants first of all to accomplish a task, and then find out about the unessential details.
- AVOID USAGE OF PHRASES IN TECHNICAL DOCUMENTS: As a technical writer, when you should keep a document simple and sweet, it also becomes essential to avoid any usage of phrases in your document. These phrases may complicate a sentence and may even prove to be dull and boring. For example, you mustn’t use phrases such as “afford an opportunity to”, “in view of the fact that”, “prior to”, “with reference to”, and “for the purpose of”. Instead, you should use simple words such as allow, because, before, and about which have the same meaning but have a soothing effect to the audience.
- ALYWAYS MAKE USE OF ACTIVE VOICE: While you are writing a document, always remember to use active voice instead of passive voice. This makes your document interesting to read and even helps you to avoid using any lengthy sentences. Active voice usually is shorter and more direct than a passive voice, which is more complicated and lengthy.
- AVOID VERBOSITY: This is the most common tip that you may find in most of web sites. Verbosity means long-windedness, which means that you must not tell the audience about how much you know about a product or a system. However, you should understand how your audience will understand your document. For this, always remember to keep your sentences in a document as concise as possible. Keep your sentences crisp and make it interesting to be read.
- ORGANIZE USING HEADINGS: It is always said that a “heading” often summarizes a particular section for what you want to say to the audience. A heading may allow your audience to browse your document, and even skip certain sections that might not of immediate interest to the audience. Thus, it becomes utmost essential to organize your document with proper headings such as “Creating a Document”, “Saving a Document”, or “Closing the Application”. In addition, it is also recommended to use a “gerund” form while writing your headings. A gerund is a verbal that ends in -ing and functions as a noun. The term verbal indicates that a gerund, like the other two kinds of verbals, is based on a verb and therefore expresses action or a state of being. A heading should not also mislead an audience. It should clearly depict the contents of that section.
