Writing Process

Technical writing refers to authoring of informative or instructive content about any technology, procedure, or a process. This presented content should be clear, precise, and provide the specific information sought by its audience. There are many types of technical documents, such as instruction manuals, online help, analysis documents, and feasibility reports, catering to a wide variety of audience. However, each document caters only to a specific group of audience, called the target audience. For example, an instruction manual caters to users learning to use an application or a product, whereas a feasibility report helps a manager plan for a project. Therefore, the author of a technical document should address the specific expectations of the specific target audience. Although there are no hard and fast rules about writing technical documents, a few basic steps can help an author save time and write a good document. Before we understand these steps, we should know what qualifies a document to be a good technical document.

Attributes of a Technical Document The only primary expectation from a technical document for any reader is only information. However, the reader also expects this information to be clear, readable, precise, and complete. A good technical document should deliver all that is expected of it.

Clarity and Readability Words, sentences, and the overall flow of information in a technical document should be simple and straightforward. This improves clarity of information and allows a reader to spend the least amount of time and effort in reading the document. Undue elaborations and complex sentences reduce the clarity of the document and hence should be avoided under all circumstances by the author. A well-structured document should have logical segmentation of content and continuity of information. Readers find such documents easy to read. and can quickly seek specific information from the document. The language used in the document should also be specific to the target audience. For example, an instructional manual should not contain technical jargon or acronyms that are not commonly used. However, a technical journal for circulation among engineers can contain technical terms and jargon.

Preciseness and Completeness Information provided in a technical document should be precise and complete. The author needs to also consider the interests of the target audience and not include any information that would not interest the target audience. For example, a user referring to an online help of a Web application would not be interested in the software components and objects used in the application. This information is best suited for the engineers in-charge of the maintenance of the application.

Authoring a Technical Document The process of authoring a technical document starts with conception of the topic or subject for the document. The decision to write a document is made based on demand for information on the topic or in anticipation of such a demand. There are four basic steps in authoring a technical document as listed below: Information gathering Designing or Structuring Authoring Reviewing

Information gathering In this step, the author collects all possible information about the topic and the audience. This collected information is the foundation for further work on the document. Exhaustive homework at this stage saves the author additional rework at later stages. Therefore, the author should collect precise and complete information about the topic. Any ambiguity in the information should be clarified immediately. It also pays to do some homework about the audience. Learning about the audience helps the author decide on the presentation style and the complexity level of information that will suit the audience best. For example, when writing a user manual for a banking application, if the audience are business users with prior knowledge in banking, the author need not elaborate on banking terminologies or processes. Author only needs to explain the application and its user interface components including the functionality of the buttons, the information to be entered in the the screens asking for user input, and how to delete incorrect or unwanted data that is keyed in. However, if the audience were end customers, some background information about banking terminologies and processes would be appropriate.

Designing or Structuring In this step, the author decides on the High Level Design (HLD) or Table of Contents (TOC) of the document. In other words, the author divides the topic into multiple sections and also decides on what and how much information should go into each section. A well-structured document ensures that the information flows through the document and there are no repetitions or gaps in the document. It also helps busy readers to easily search of information from the document.

Authoring This is the step when the author actually writes the document. The author should ideally not have any trouble at this stage, if the structure of the document is well defined and the author knows exactly what information should go into the document as he/she has decided in the previous step. He only needs to take care that the language used is clear and correct. The author can also use figures, illustrations, or other graphics to describe complex ideas. However, if the author feels the need to revisit the design or finds some gap in information at this stage, then authoring can become complicated. The author would not be wasting time but also compromising on the quality of the document.

Reviewing To err is human. However experienced, proficient or knowledgeable an author might be, the chances of an error or scope for improvement in a document is never zero. Therefore, the author should always review the document immediately after completion. Errors can be of many types. Apart from grammatical and typographical errors, there can be technical inaccuracies, format errors, and incorrect ambiguous graphical elements in the document. If necessary, the document should be sent to respective experts to identify and rectify errors. Depending upon the size and complexity of the content, documents might need several rounds of review and verification by specialized professionals. However, the authoring process will be complete only if every effort is made to eliminate all errors from the document.