Don’t Dread the Documentation

http://www.gannett-cdn.com
ISE Magazine – Volume 48: Number 08
By Theresa Barker

Writing documentation is the part of a project many engineers and scientists find to be the most dreaded. As petty as it seems, documentation is important. However, some engineers may find it challenging to write well-written documents to communicate their engineering thinking and design process. Engineering design process can be used to develop effective and clear written documents.

Firstly, you have to define the overall goal. What information do you want to communicate to the reader?  Documentation does not mean writing paragraphs upon paragraphs, some information is easier to understand when presented in photographs, diagrams, charts, tables, or equations. Secondly, you have to research the customer. Who is the target audience?  There are three key aspects to understand your target audience:

1. Background: understanding this helps you to determine the level of details and writing tone
2. Purpose: understanding this helps you to choose the structure of the document andhow to organize the content
3. Level of understanding: this helps you to decide whether to give pointers on additional information on technical knowledge elements

Unfortunately, sometimes you just do not have enough information on the target audience. Therefore, you should write it with different kind of readers in mind. Give features that may help different people to understand, like sidebars for noncritical information, bulleted list, and boldface font for significant parts.

Now that you know how to write a good document (from your point of view), how do you know that the reader will understand it? Compare it with models and established standards for specific documents. If there is none available, take a look at documents that you have found effective and adopt its effective aspects for your documentation. It is even better if you can ask the actual readers to tell you what they need to see in your document. But if you cannot, ask people to put themselves in the actual readers’ shoes and ask them about what may be confusing and not in your documents.

If the purpose of the document is persuasion, you may want to include these points:

• Identify the reader’s main interest in your topic
• Address a need for the concept or view you want the readers to adopt
• Provide a solution
• Consider the reader’s other options and how your idea, product or service does a better job of addressing the needs against those options