6

Instructional writing is an art

– Kumar Dhanagopal

Instructional writing is at a point today where most of us agree that adhering to certain writing styles can almost certainly make instructions more effective. Increasingly, organizations view the task of writing instructions as a rule-based activity that any person who can write reasonably well can perform routinely. Some organizations even invest in automated tools to ensure compliance with established style guidelines concerning parallelism, imperative tone, and so on. Organizations strive to achieve standardization in instructional writing: that is, ensure that every piece of writing bears a uniform organizational “tone” rather than individual writers’ voices. Written instructions are seen as mass-produced commodities rather than as unique pieces of art. In addition, with the entry of XML-based authoring, even the obviously “artistic” parts of technical communication—information layout and formatting—are automated. It appears, therefore, that instructional writing cannot be an art.

In this article, I argue that despite the seemingly mechanical context and nature of the underlying process of writing instructions, written instructions ARE works of art, because creative thinking and problem solving are essential to achieve the following goals of instructional writing.

  • Convey complex information simply
  • Address the needs of a wide range of users
  • Balance conflicting interests
  • Gather hard-to-find information from diverse sources
  • Organize content based on audience needs
  • Deliver content in a usable form
Convey complex information simply

Rules and guidelines for writing alone cannot help writers transform technical information into content that is easy to understand. A fair degree of iterative experimentation is required. In addition, often engineer-speak is complex because the creative thinking that occurs when a product is being engineered filters through into the speech and writing of engineers, rendering their text ambiguous and confusing. Technical communicators need to eliminate this confusion and ultimately improve the usability of the text (Byrne).

Address the needs of a wide range of users

Technical writers need to understand the language of the subject matter experts and that of the end users. Often, use cases should be imagined and anticipated. The right mix of textual and non-textual information elements should be used so that the information is useful regardless of the reading style of the user. In addition, the level of detail that different readers want varies: The instructions should be idiot-proof and yet not offend the sensibilities of experts who do not require handholding.

Balance conflicting interests

Technical communicators need to balance conflicting needs of stakeholders. Stakeholders in marketing might not want documentation to reveal too much about problems in the product. Developers would perhaps be happiest when the most hi-tech of the features is highlighted in the documentation. The user needs useful and usable information, just that and nothing else. Balancing these conflicting priorities requires tact and creativity.

Gather hard-to-find information from diverse sources

Information about how a product works (for example) is often not readily available, and so should be painstakingly discovered and harnessed from various sources. This activity is time consuming, requires enormous patience, and, most importantly, requires the use of creative “research and investigative skills” (VanArsdall).

Organize content based on audience needs

Depending on the needs of the audience, the technical communicator should decide how to organize paragraphs and sections, which topics should be reused, how topics should be interlinked, and so on. According to Sarah O’Keefe, “Technical communicators add the most value and have the most opportunity for creativity in crafting sentences, paragraphs, topics, and groups of topics that explain complex concepts to their readers”.

Deliver content in a usable form

The final output should be produced in a form that every user can find quickly and use, regardless of the condition of use. A car user manual that is provided in a DVD, as one manufacturer did recently, while certainly hi-tech, is practically useless. Understanding the usage environments and coming up with a delivery format that caters to all of them within the specified budget requires creative thinking.

Conclusion

Technical communicators need to understand audience needs; gather, write, and organize information, balance conflicting interests within and outside the organization they work for; and deliver complex information in a simple and usable form. Each one of these goals calls for creativity, imagination, and intuition—all clearly “artistic” qualities.

References:

About the author:

Kumar Dhanagopal (kumards_99@yahoo.com) works as a senior doc project lead at Oracle.

About the illustration:

Used with permission from Nirupama Singh.

6 Comments

  1. Well written article. Instructional writing is certainly an art. Just wanted to add to the last point on usability. As more and more content is being found online, (or should I say not being found online;) SEO plays a big part in making the content being created, ‘findable’ It is difficult to think of every possible situation and user when creating these instructions. What the user wants may not be what you thought they want. And even if you have thought of it, the user may search for it using different key words or phrases. That’s where our style guides fail. Our content is style compliant, but many users don’t find it simply because they use different keywords or they have a different perception of an issue.
    For example, I may have a very elaborate document that explains how to increase screen resolution. However, the user is searching for some way to increase the size of his font as everything appears too small to read. When he searches for ‘increase size’, he gets an article on how to increase size of outgoing email (or everything related to font size on a browser). This does not solve the problem as it is only the text size on the browser that is changed. Everything else still appears small! One of the ways by which you can get such insights is to implement a robust feedback mechanism. If this is not done, it becomes meaningless to say – RTFM (Read the freaking Manual).

    • Thanks for the feedback, Nibu.

      >>> “SEO plays a big part in making the content being created, ‘findable’…”

      True. And I think a good index would go a long way toward helping readers find what they want.

  2. One knows that life is expensive, but people require cash for various stuff and not every man gets enough money. Therefore to get quick home loans and just bank loan would be good solution.

  3. thanks for sharing the information.
    On your right side (west of where you are when you face the Montparnasse Tower), the apparel shops in the surrounding streets offer attractive bargains.
    http://www.earfaves.co.uk/
    Kind Regards,
    Jor Dearme

Comments are closed.