This article originally appeared in the 2018 Autumn issue of the Communicator Journal

Around 50 years ago — at the same time as Communicator was first published —a methodology was developed for ensuring that instructional text was optimised for readers and learners: Information Mapping. This defined a set of principles for writing well. In time, other methodologies were also developed, but all have one thing in common: they all include principles that address a wide range of factors involved in ensuring that readers can extract and understand the information they need.

I believe that if there’s one skill that technical communicators can develop to keep themselves relevant in a rapidly changing world, it’s learning these principles of how to write well.

These principles have changed little over time. Used well, they set technical communicators apart. Anyone who can master them has a skill that remains current and valuable whatever changes happen with technology, authoring tools or the workplace.

What do we mean by ‘writing well’?

Writing well goes beyond perfect grammar and well-crafted sentences, though of course, these are essential skills. However, to create information that is genuinely useful and effective, we need to apply a wider set of principles.

Figure 1 'Principles of good writing'

Figure 1 lists some of the principles that appear across methodologies and guidelines.

Why writing well matters

‘In the past twenty years, we have seen a significant increase in research projects concerned with the man-information interface. The reasons for this scarcely need repeating. We have more information to handle in almost every job and discipline. This information is increasingly complex. People switch jobs more often, thus requiring more and speedier retraining. Technology changes; men must learn to use the new. The information-generating capabilities of the computer have surpassed all predictions.’ (Horn et al. 1969)

These words were written nearly 50 years ago. While the language is a little outdated, the sentiment is still relevant today. We live in a rapidly changing world where we are faced with high volumes of complex information and need to be able to understand and act on it quickly.

The ability to create information that genuinely helps people use it gives a competitive edge to products, businesses, and the users of that information. For example, the latest smart TV is less impressive if people don’t understand its exciting new features; a new IT system is a waste of money if no one understands how to configure it.

Writing well is a skill

In the 1960s, Horn and his colleagues were drawing together research in fields such as cognitive science, to identify ways of improving instructional materials (including what we would now call e-learning, help and manuals). They identified that applying a set of these research-based principles to technical information led to quantifiable improvements in the abilities of learners to use the information. Their methodology was called Information Mapping, and is still in use today (Information Mapping website).

Since then, various other effective methodologies have also been developed. And yet much of the information we encounter every day is hard to understand or use. Clearly, writing well is difficult. But it is a skill that can be learned, and anyone who has this skill can completely transform the experience of using the information that people encounter in their daily lives.

Writing well is based on research about how readers learn

The principles that Horn and his colleagues identified became the Information Mapping method. But they’re also the same basic principles of modern information design, whether it’s developing a training course to be read on a mobile device, creating embedded software help, or writing the manual for a piece of industrial equipment.

This isn’t an article about Information Mapping. But what’s interesting about this methodology is that it’s explicit about being based on academic research, and draws direct lines between research findings and practical principles for creating information.

Figure 2 - examples of information mapping

Figure 2 shows some examples from an early article about Information Mapping (Horn et al. 1969).

This research-based approach is interesting to technical communicators because it professionalises the skill of technical communication. Good writing isn’t a matter of opinion; it’s a matter of applying proven principles.

Writing well improves usability

Other research confirms that applying common principles for writing well is effective at improving its usability

For example, a 1997 study by Nielsen Norman Group identified that only 16% of visitors read all the words on a web page; the majority just scanned the page (Nielsen 1997).

This research looked at the effectiveness of improving text to make it easier for readers to extract information by scanning. The researchers applied a small number of principles to improve a piece of promotional information:

  • Concise text
  • Scannable layout
  • Neutral language.

These are common principles for any kind of content; they don’t just apply to creating web pages. Figure 3 shows a sample of the text before and after applying these principles. The result of these changes was a 124% improvement in usability: clearly, writing well matters.

Writing well prepares content for structured tools

Horn claims Information Mapping as the first structured authoring technique (Horn 1993). In fact, it’s no coincidence that information prepared according to Information Mapping principles is structured. As far back as the 1960s, Horn and his colleagues were looking ahead to a world where information might be held in a database and learning
materials could be assembled from there.

But methodologies that don’t have this as an explicit goal also help prepare information for structured tools. For example, a common principle in any methodology is to break information down into small chunks, each with a specific purpose. This is also an essential step for any structured authoring environment.

Another common principle is to connect chunks together into structures and patterns. These repeatable structures are another essential element for structured authoring.

Writing well optimises content for localisation

The principles behind writing well also support localisation. Information that is easy to understand is easier to translate. Information that is concise and only includes what the audience needs to know has a lower word count, which reduces translation costs. What’s more, applying principles of chunking and structuring make it easier to substitute locale-specific text, and also prepares the content for compatibility with XML-based localisation tools.

What’s more, applying principles of chunking and structuring makes it easier to substitute locale-specific text, and also prepares the content for compatibility with XML-based localisation tools.

Writing well makes technical communicators valuable

Many technical experts can write grammatically and accurately. Some can even write sentences and paragraphs that explain concepts and procedures clearly. Few have the ability to analyse their audience and content to understand what their users really need to know. Even less common is the ability to structure and format the information to make it easy for readers to extract the knowledge they need.

With this skill, technical communicators have the ability to add value by creating information that gives businesses a competitive edge, among other benefits (Potts and Hart 2015).

Research-based methodologies for writing well are particularly significant because they establish the technical communicator as a skilled practitioner, following principles that result in quantifiably better outcomes for your materials. They also equip technical communicators to make and ‘defend’ decisions about information, often in environments where the common sentiment is ‘anyone can write — we’re just too busy so we employ technical authors to do it’.

Writing well doesn’t change when technology changes

Once you’ve mastered the skill of designing and creating good quality information, you have a skill that continues to be relevant even as technology and the way we consume information change.

In fact, the skill may even become even more important. We’ve already seen an example where the principles of writing well made a piece of web content more usable (see Figure 3). Other research by the same group also suggests the principle of brevity or conciseness becomes more important than ever when information is consumed on a mobile phone (Nielsen 2011).

Figure 3. A piece of promotional material before and after rewriting to improve scannability

Figure 3. A piece of promotional material before and after rewriting to improve scannability (from Nielsen 1997)

How to write well

The same fundamental principles apply whether you’re creating an aircraft maintenance manual or UI microcopy, for all authoring tools, and whether you’re writing for technical experts or novice users. I don’t mean to suggest that an aircraft maintenance manual should look the same as an embedded help pop-up in Skype, but the same principles apply to creating these very different materials.

Even where traditional wisdom suggests it’s not so important to optimise information if it’s going to be used by technical experts, research suggests that this is not the case. For example, a usability study described by Loranger found that ‘even highly educated online readers crave succinct information that is easy to scan, just like everyone else’ (Loranger 2017).

How to learn how to write well

Various methodologies provide principles and guidelines for how to create information that works. Information Mapping is one of the more established methodologies; at 3di we also use the guidelines in Writing Quality Technical Information (Carey et al. 2014), both for training and for evaluating information. But there are other methodologies that are also effective, so becoming familiar with, and applying, whichever you find most suitable will get you a long way.

Keep your skills current

While the fundamental principles of writing well have hardly changed, there are always new insights into how to apply these principles. For example, Pratt (2017) describes research, which, in some contexts, suggests that a more conversational tone is the most effective way to communicate with some audiences.

And, of course, Communicator is an excellent resource for keeping in touch with the ways other technical communicators are applying these principles.

References

Carey M; McFadden Lanyi M; Longo D; Radzinski, E; Rouiller S and  Wilde E (2014), Developing quality technical information, IBM Press, Upper Saddle River, NJ.
Horn R E (1993). Structured writing at twenty-five, Performance and Instruction 32, (February): 11-17.
Horn R E, Nicol E H, Kleinman J C and Grace M G. (1969) Information mapping for learning and reference, Information Resources Inc, Cambridge MA.
Information Mapping (accessed September 2021)
Loranger H (2017) ‘Plain Language for Everyone, Even Experts’. Nielsen Norman Group, (accessed September 2021)
Nielsen J (1997) ‘How users read on the web’, Nielsen Norman Group, (accessed September 2021)
Nielsen J (2011) ‘Mobile content is twice as difficult’, Nielsen Norman Group, (accessed September 2021)
Potts R and Hart R (2015) ‘Helping organisations grow’ Communicator, Spring 2015 Special Supplement: 5-7 (accessed September 2021)
Pratt E (2017) ‘A change in tone’ in Crabbe S (eds), Current Practices and Trends in Technical and Professional Communication, Croydon, UK: Institute of Scientific and Technical Communicators, pp 75-88.

About the author

Rachel is our Lead Consultant, advising customers on documentation strategy, and helping our growing team of technical writers to develop their skills and hone their insights. She is a Member of the Institute of Scientific and Technical Communicators and also contributes to the ISTC’s award-winning journal.

CONTACT ME

 

Please rate this article

0 / 5 0

Your page rank: