The Manual of Technical Communication
Authors: Students of University of Alabama in Huntsville
Publisher: UAH Business and Technical Writing Program, 2014
There's one aspect of being an engineer that's often overlooked by engineers. Engineers focus on solving problems, building systems, writing code, designing models, and so on. They enjoy this sort of work but what they don't enjoy is to communicate. Perhaps this is because they lack the essential skills to do this right. Most university degrees in engineering include at least one module on technical communication but students take this module out of necessity rather than motivation. It's important for young engineers and students alike to realize that technical communication is the "x-factor" that could make them stand out from the crowd. This book written and edited by students at the University of Alabama in Huntsville is a practical guide and a good starting point for all engineers.
Why is technical communication so important? An engineer's work cannot see the light of day unless she can explain her design decisions to her peers; or rationalize the budget and cost considerations of a project; or describe clearly the idea that's in her mind; or convince her boss why something needs to be done differently; or make a presentation to potential clients; or write an email that summarizes what was discussed at a lunch meeting. If as engineers we are unable to put across our ideas clearly, we will probably not reach our full potential and put to risk the projects we work on and our careers in the process.
This book starts with an overview of technical communication and then dives into explaining the process of writing different types of documents. These can range from white papers to memos, from user manuals to resumes, from developer documentation to technical proposals. These are explained in the book in separate and independent sections, which makes it easier for readers to jump to sections relevant to their immediate needs.
The book does a good job of explaining what document types are suited for what situations. For example, a proposal is somewhat a cross between a sales pitch and a report. It should address the problem, propose a solution and state the budget and schedule. A white paper can be seen as "marketing with content." It's mainly informational. It establishes technical expertise and credibility. News releases are informational in nature but there's also this desire that media will pick them up and feature them in the news. Documentation can be for users or for developers. Procedures are to guide readers to achieve something by following a sequence of steps. Standard Operating Procedures (SOPs) are well known in engineering because they allow operators to do things consistently. They are important for tasks that are long, complex or dangerous.
It goes without saying that what and how we write depends on who the readers are and what is their level of technical competency. The purpose of writing should also be clear. Is it to guide the reader to do something? Is it to inform? Is it to change attitude? Will the document be read on a computer, on the printed page or as a poster on a wall? In most cases, except perhaps for posters or flyers, writing should begin with an introduction or summary, should end with a conclusion and contain the main text in between.
The book's first chapter also gives some useful tips. Use active voice because this can make sentences shorter and clearer. Choose simple words. Avoid turning verbs into their noun forms so that writing becomes action oriented. For example, it's better to say "Managers will implement the new policy on Monday" rather than "Implementation of the new policy will occur on Monday." Avoid weak verbs such as have, make, deal with, give and use. Don't say "blue in colour" or "return back" when "blue" and "return" would suffice. When giving instructions such as in a user manual, write them down as commands rather than statements. Compose your sentence so that the main idea is conveyed correctly. Use illustrations to explain, to interest and to engage the readers. Because of the way documents are made these days, writers should also become conversant in the tools: Photoshop, GIMP, Microsoft Office, and so on.
A good corporate document is probably made in a collaborative fashion by many individuals. You may be the original writer but the content may come from Subject Matter Experts (SMEs). To gather data, you may have to interview SMEs, do online research or better still observe how users are using the system. Your peers and supervisors may suggest changes. Illustrations may come from someone expert in creating them. A designer may do the layout and styling so that the document conforms to the corporate branding. The document may be reviewed by the legal team for approval.
Since this book was written three years ago, new changes have appeared in the way people communicate. While office memos are still common, shorter forms via Slack are gaining wider acceptance. When sharing code on GitHub, often documentation is either lacking or poorly written. Traditional user manuals are going away in preference to API documentation. Since emails are so widely used, a section on email etiquette might have been useful. Otherwise, this is a short and well-written book that all engineers can read. The book also contains links to sample writing that we can study for a better understanding of each topic.
About the Author
Arvind Padmanabhan graduated from the National University of Singapore with a master’s degree in electrical engineering. With more than fifteen years of experience, he has worked extensively on various wireless technologies including DECT, WCDMA, HSPA, WiMAX and LTE. He is passionate about tech blogging, training and supporting early stage Indian start-ups. He is a founder member of two non-profit community platforms: IEDF and Devopedia. In 2013, he published a book on the history of digital technology: http://theinfinitebit.wordpress.com.