People Innovation Excellence

Don’t Dread the Documentation
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

Published at :
Leave Your Footprint

    Periksa Browser Anda

    Check Your Browser

    Situs ini tidak lagi mendukung penggunaan browser dengan teknologi tertinggal.

    Apabila Anda melihat pesan ini, berarti Anda masih menggunakan browser Internet Explorer seri 8 / 7 / 6 / ...

    Sebagai informasi, browser yang anda gunakan ini tidaklah aman dan tidak dapat menampilkan teknologi CSS terakhir yang dapat membuat sebuah situs tampil lebih baik. Bahkan Microsoft sebagai pembuatnya, telah merekomendasikan agar menggunakan browser yang lebih modern.

    Untuk tampilan yang lebih baik, gunakan salah satu browser berikut. Download dan Install, seluruhnya gratis untuk digunakan.

    We're Moving Forward.

    This Site Is No Longer Supporting Out-of Date Browser.

    If you are viewing this message, it means that you are currently using Internet Explorer 8 / 7 / 6 / below to access this site. FYI, it is unsafe and unable to render the latest CSS improvements. Even Microsoft, its creator, wants you to install more modern browser.

    Best viewed with one of these browser instead. It is totally free.

    1. Google Chrome
    2. Mozilla Firefox
    3. Opera
    4. Internet Explorer 9