Technical writing in computer hardware electronics and aerospace

What is Technical Writing?

Technical writing is a style of formal writing used in various fields as diverse as computer hardware and software, chemistry, aerospace industry, robotics, finance, consumer electronics and biotechnology. In short it is conveying specific information about a technical subject to a specific audience for a specific purpose.

Presentation of information is indeed very important as it helps the reader in solving a particular problem or in understanding a particular technology or product. The words and graphics of technical writing are meant to be practical i.e., they should be able aid in communicating in simple terms; a body of factual information that will help the audience understand a subject or carry out a task.

DDLC

DDLC stands for document development life cycle; it is a linear collection of several phases that are used by a technical writer to create a clear, concise, informative and well structured technical document. Conceptual knowledge of DDLC is crucial in creating good technical documents and thereby in achieving success in the field of technical writing.

Various phases of DDLC are:

Requirement Specification

The Requirement specification phase is all about content collection and content representation. It involves determining

• Audience – who is going to benefit from this document or who is going to use the document?
• Time – The time frame and various deadlines to be followed through the entire project
• Quantity/Number of pages – The size or number of pages in the document.
• Tools – The tools to be used for creating the document.
• Document type – whether the doc is a user manual or help guide etc.
• Templates – The templates and style guides to be used in preparing the document
• Reference Documents – The reference documents client might provide to aid in the creation of the document.

A lot of times the, thewriter must usually interview the user as well as a subject matter expert (SME) to get detailed information and to find out what is needed or required. In the case of writing software documents the writer is supposed to interview or talk to the programmers and whereas to write about hardware, the writer talks to an engineer, technician or manager. The method of conducting the interview may vary from just talking with the person and taking down notes to tape recording the conversation. It is a good practice to have a list of questions on hand during the interviews with the SME’s or other technicians. Other sources include the internet, reference documents etc. The tools that are to be used in making the document are decided on the basis of the document type. For example, RoboHelp is used for creating online user guides and MS-Word is used in creating user manuals.

Audience Analysis

The complexity of a document is decided by the audience it caters to. Audience analysis phase involves determining the audience level. This can be done by either talking to the developers of the particular product or technology or through the SME. Also we can learn more about the audience level by talking to those the product is intended for. Formally, audience can be categorized into three levels based on how much they already know about the product or the technology.

Novice – A novice user is completely new to the technology or product the document is about and usually has very little or no knowledge about it. Documents intended for these kinds of audience need to contain everything about the technology starting from the very basics.

Mediocre – A mediocre user has a general knowledge about what the product is all about but need to

Technical / Experts – An expert or technical user has an in depth knowledge of the product , technology or software and is usually looking for only particular information.

Product Analysis

Product analysis phase involves deciding which of the two approaches presented below is more appropriate in writing about the technology / software.

• Menu driven
• Thematic approach

Document Flow

The purpose of this phase is creating an outline for the required document i.e., creating the skeletal framework of the document. A skeletal framework usually includes Preface or introduction, Table of Contents and figures, Chapter information and sequence, bibliography, index etc. All the elements of the document are ordered serially to prepare the “Table of Contents (TOC) “. The output of this phase is to produce a clear view of how the document will be structured.

Gathering Information

Now that the technical writer has a skeletal framework, he needs to gather the information required to fill in the blanks. For this purpose he needs to again communicate with the developers, SMEs and also find some of his own resources through the internet or the reference documents he is provided with.

First Draft

This phase involves preparing the first draft of the required document following the pre approved document plan and time schedule.

Review

The purpose of this phase is to review (self, peer, technical, and final) the completed document against the requirements specification document, style guide and template determined during the requirements specification page.

Peer review

Peer reviewing is subjecting the authors work to the scrutiny of other employees who are experts in the same field. Peer reviews usually need a community of experts in the same field given field, who are qualified and can perform an impartial review. Even though there are a lot of speculations about peer reviewing, it actually encourages authors to meet the accepted standards of their discipline and also prevents the dissemination of irrelevant findings, unacceptable interpretations, personal views and unwarranted claims.

Technical review

Technical reviewing aids in creating a technically superior version of the work product that is reviewed, which is done either by correction of defects or by recommendation or introduction of alternative approaches. Technical reviews are also a form of peer reviews but in which “a team of qualified personnel examines the appropriateness of the document for its intended use and also identifies deviations from the mandatory specifications and standards”. Technical reviews sometimes provide recommendations and examination of various alternatives.

Editorial review

Editorial reviewing aims at improving the readability of a manuscript. The reviewer parses through the manuscript to find whether it can be further simplified or clarified. The reviewer either makes changes or makes marginal notes and a written report and then returns the manuscript to the writer for further revision.

Second draft

The second and the final draft of the technical paper is out only after a final review. Once the document is free of any grammatical or technical related errors and follows all the guidelines, it is ready for publication.