Technical authoring and the use of Plain English

Here at Armada HQ we have been working hard on the launch of our latest website. This has involved a number of discussions over the meaning of some of the terms that we use day-to-day in technical authoring.

It has become apparent that as technical authors we are as guilty as anyone for using technical terminology, acronyms and abbreviations.  This seems to contradict the whole profession of technical authoring. We have some members of our technical authoring team who are relatively new to the world of technical communication and are not familiar with some of our jargon.

As a technical author, I understand how important it is to write in plain English. One of the first rules of technical authoring is not to make assumptions; the reader may not understand all of the terminology associated with the product you are documenting.

I present you with some examples:

• One man’s knowledge base is another man’s information centre.
• What actually is online help? Does it refer to any form of user assistance that can be accessed via the internet?
• What is context sensitive, localisation, LMS, UI?

Maybe we like the smoke and mirror illusion that technical authoring terminology offers. However, ask yourself why are the skills of a technical author called upon and you realise that it is because we are experts in communication. We must practice what we preach and consistently demonstrate that we can simplify the information that end users are seeking. Why use over-complex words when we pride ourselves in being expert communicators? We don’t want to confuse the user experience by throwing in terminology that they have to ‘Google’ to understand. Sometimes writing in plain English can be challenging, especially when faced with a barrage of technical jargon from within the technical authoring profession!

The solution

Is the answer an online knowledge base incorporating a glossary of terms for every document you write? Answers on a postcard please.

Testing technical communication knowledge

Testing users on technical authoring terminology is easy.  I need a SCORM compliant e-Learning module with a UI that is intuitive to the target audience. Although I must remember to develop it in a responsive design and link the results to our localised LMS.

Summary

I rest my case.

My other pet hate is ‘business speak’ but that is another story. I will save that rant blog for another day! I cannot be the only information architect with a bee in her bonnet. What are your pet hates?

Glossary of terms

This list only refers to the terms used within this document.  There are an infinite number of other terms used in the technical authoring world. These may, or maybe not be, a mystery to non-believers!

Context sensitive

Where the relevant help topic is accessed directly from the software.

e-Learning

Interactive online training and software simulations.

Knowledge base

A single holding place for all of your company documentation.  This is usually held online either on the internet or your corporate intranet.

Information architect

Technical author.

LMS

Learning Management System.
‘A software application used in the administration, documentation, tracking, reporting and delivery of e-learning education courses or training programs.’ Ellis, Ryann K. (2009), Field Guide to Learning Management Systems, ASTD Learning Circuits.

Localisation

Adapting and translating user assistance and documentation for an alternative target market. Localisation ensures that documentation is culturally appropriate in alternative languages.

Online help

User assistance and documentation that is available through your organisation’s intranet, extranet or website.

Responsive design

User assistance and documentation that is easy to read and navigate regardless of screen size. The online format automatically adjusts according to the device used to view it: mobile phone, tablet or desktop.

SCORM

Sharable Content Object Reference Model.
A set of technical standards for e-Learning software. Developing SCORM compliant e-Learning guarantees compatibility with your Learning Management System or any existing e-Learning that you may have.

GUI/UI

Graphical User Interface.
The means in which a person controls a software application or hardware device. An intuitive user interface encourages interaction with an application.