Speare Blog posted on Apr 20 2017 6:53PM

How to Create Technical Documentation

by Chris Angelopoulos

Introduction

Launching a new product can be an exciting adventure and an incredible amount of work. Ensuring that end users can become acquainted with the new technology is critical for success. The task of bridging the gap between engineers and users falls to the technical writer. When documentation is complete, it should be focused, clear, organized, accurate, and interesting enough to hold the attention of the reader.

Know the Subject and the Reader

Before beginning to write, it is imperative to truly comprehend the subject of the documentation. This will likely mean taking the time to use the product and developing questions that will turn into answers. The intended audience will greatly impact how documentation is written. It is necessary to ask if the audience has a base of knowledge to understand the concepts being discussed. A non-technical user may appreciate a brief discussion of the underlying concepts, or the “why”, before moving on to discuss the “how”.

Providing Clarity

Technical writing should not be a minefield of cryptic terms that causes readers to abandon all hope of figuring out how to use the product. Define terms, explain ideas, and provide references to other sections of the documentation where appropriate. Use clear language and constrain section length to the minimum required to accurately communicate an idea.

A Map for Directions

Well-organized writing of any kind is easier to follow. This is especially important with documentation. Creating an outline gives direction to the writer and assists the reader in solving specific problems without embarking on a frustrating, protracted search. Speare, the software used to create this article, offers a powerful way to build structure into a document from the very start. Concepts entered into the app serve as Building Blocks. These elements can be rearranged to create an outline or filed under proper sections to enhance detail.

Now What Do I Do?

Creating understandable action steps can remove a good deal of irritation from the process of reading documentation. Usually, a reference guide is consulted when an issue arises. Cataloging technical features is important but should be accompanied by methods for solving problems.

Are You Still Watching?

Technical writing is descriptive and aims to be professional. That should not imply that it must be sleep inducing. Documents that are entertaining as well as informative are easier to write and read. It could mean the difference between producing a document that helps users become familiar with the material and writing a paper weight that protects a small corner of office space from dust accumulation.

Let's Try That Again

Documentation is rarely perfect the first time. Proofreading all work is a must. It also can quickly become out of date as product versions change. The challenge is to create a living document that is constantly updated with the features it covers. This is another motivation for order and clarity. The writer must occasionally become the reader.

Summary

Creating technical documents is an in-depth process that requires an eye for detail and a commitment to accuracy. The likelihood of a successful outcome is greatly increased by thoroughly understanding the subject being documented and choosing the right tools for the job. Only then will it be feasible to fulfill the calling of the technical writer: to learn complex systems and make it possible for others to do the same.