Technical Writing for Business People

Carrie Marshall

• Publisher: BCS, The Chartered Institute for IT
• Year: 2018
• Print ISBN: 9781780174464
• eBook ISBN: 9781780174488
• Topic: Computer Science
• Subtopic: Computer Science General
• Index: Computer Science

Technical writing is about communicating key information to the people who need it. It might be a manual for an application, a guide to using heavy machinery, or a diagnostic aide for medical practitioners. It needs to be clear and it needs to be precise. This book shows you how to achieve this and more. Whatever the content or context, in this book you'll discover the essential tools and resources that you need to create technical writing that works for everyone.

1 WHAT IS TECHNICAL WRITING?

Technical writing is about communicating key information to the people who need it in the most suitable way and format. That might be printed material, but it could also be a graphic or a video.

That information might be a tutorial for a software application, a guide to using heavy machinery safely, a diagnostic aide for medical practitioners or a guidance note about new legislation.

If you work in a technical or specialist field of any kind you may be a technical writer already.

According to the Society for Technical Communications, technical communication has one or more of the following characteristics:¹

1. Communicating about technical or specialised topics, such as computer applications, medical procedures or environmental regulations.

2. Communicating through printed documents or technology, such as web pages, help files or social media sites.

3. Providing instructions about how to do something, regardless of the task’s technical nature.

According to the Institute of Scientific and Technical Communicators:²

Technical communication tends to answer the six important questions. These are: what, when, why, where, who and how – and often with an emphasis on the ‘how’. It may be provided as text, images, video, simulations, online help or in a number of other formats. The information in technical communication is targeted to the needs of the people using it to complete a task.

Technical writers are often translators. We take things that others may find complex or intimidating and simplify them, making them clear and user friendly.

Your organisation will benefit from effective technical writing. Effective technical writing clears up confusion, and helps people to understand crucial concepts, new systems and important procedures. A help document that isn’t helpful or training materials that don’t help the trainer cost money, both in terms of time spent and customer or employee satisfaction. The technical writer enables the business to communicate more efficiently and more effectively – and if they encounter particular issues that cause particular problems, they can be the early warning of issues the business really needs to fix.

Technical writing is often thought of as the creation of help files and user manuals, and it does include those things. But it may also mean creating reports about technical or scientific issues, or writing safety guidance on how to operate potentially dangerous products, or designing a flow chart on how to troubleshoot an electric car, or creating the datasheet for a smartphone.

Here’s an example from Apple, explaining what to do with a device that has frozen.³

On an iPhone X, iPhone 8, or iPhone 8 Plus: Press and quickly release the Volume Up button. Press and quickly release the Volume Down button. Then, press and hold the Side button until you see the Apple logo.

This is from the specification sheet for the Samsung Galaxy S8 phone, explaining the options for playing its video on a TV.⁴

Wireless: Smart View (Miracast 1080p at 30 fps, mirroring support available for devices supporting Miracast or Google Cast.)

With cable: supports DisplayPort over USB type-C. Supports video out when connecting via HDMI Adapter. (DisplayPort 4K 60 fps)

And this is an example from barbecue firm Weber on how to cook safely.⁵

Oil should only be used if absolutely necessary and applied to the cooking grate using kitchen roll.

Although I’ll talk about technical writing throughout this book, technical writing in the 21st century usually means more than just writing. The job of a technical writer is to help people with the things they need to know, and to use whatever tools enable them to do that best – and today, that toolkit contains all kinds of media and apps.

THE TECHNICAL WRITER’S TOOLKIT

The days when all technical writing was printed paragraphs or lists on paper are long gone. While printed text is still important, it’s become part of a toolkit that embraces a variety of content and delivery methods, including:

• Audio and video. Such media may involve a range of techniques and content: a video might be narrated over footage of the task being described, or could be scripted to deliver a promotional message. The content may be delivered from a streaming site such as YouTube, from the organisation’s own website or via a smartphone or tablet app.

• Online knowledge bases and chatbots. A knowledge base is a fancy name for a help system: they are databases of information, usually presented in the form of short articles, that you can search for specific words, phrases or topics. Chatbots are an evolution of knowledge bases. Instead of users searching for the solution to a problem and wading through pages of results, chatbots are automated apps that deliver human-style interaction to help people get the information they need.

• Content management systems (CMSs). CMSs are apps, often web-based, that are designed to collate, manage and publish a wide range of content. One of the most famous CMSs is the online publishing platform Wordpress, which is used for small blogs and giant media sites alike.

• Social media. From Twitter tweets to lengthy articles on LinkedIn or Medium.

• Downloadable documents. Often in Word or PDF format.

As you’ll discover in later chapters, different media require different approaches and different kinds of writing.

THE MOST IMPORTANT THING YOU NEED AS A TECHNICAL WRITER (AND NO, IT ISN’T A REALLY GOOD PEN)

The most important thing you need isn’t talent, a way with words or a whizzy word processing app. They all help, but the most important thing is time.

Technical writing is a craft, not an art, and the more time you spend doing it, the better you become. If you have time to learn the ins and outs of the subject (or to interview the people who do), time to plan, time to create the appropriate documents and time to fine-tune, edit, assess and test them, then you should find that you create technical writing that does its job very well.

That doesn’t mean you won’t benefit from some expert advice though. There are traps you don’t want to fall into, bad habits you don’t want to adopt and lots of killer tips and tricks that can make your writing even better. And they all just happen to be in this book.

KEY TAKEAWAYS

• Technical writing communicates key information to the people who need it.

• It communicates that information in the most effective way.

• The most important thing you need for good technical writing is time.

¹ Society for Technical Communications (n.d.) Defining technical communication. Available from www.stc.org/about-stc/defining-technical-communication/

² Institute of Scientific and Technical Communicators (n.d.) Why do we need technical communication? Available from www.istc.org.uk/value-of-technical-communication/why-do-we-need-technical-communication/

³ From this page: https://support.apple.com/en-gb/ht201412

⁴ From this page: www.samsung.com/global/galaxy/galaxy-s8/specs/

⁵ From this page: www.weber.com/GB/en/top-bbq-tips/safety/gafc3.html

2 SEVEN STEPS TO HEAVEN: THE TECHNICAL WRITING CYCLE

There may have been three steps to heaven for Eddie Cochran,⁶ but for a technical writer there are seven. The process of creating and publishing technical writing can be broken down into these seven parts:

1. identify the specification, audience and scope;

2. planning;

3. research and writing;

4. testing, reviewing and revision;

5. deliv...

Table of contents

• Front Cover
• Half-Title Page
• BCS, THE CHARTERED INSTITUTE FOR IT
• Title Page
• Copyright Page
• Contents
• List of figures
• Author
• Preface
• 1. What is Technical Writing?
• 2. Seven Steps to Heaven: the Technical Writing Cycle
• 3. Know Your Audience
• 4. Break it Down: the Importance of a Task-based Approach
• 5. Assume Nothing
• 6. Vanquish Vagueness
• 7. Don’t be Yourself
• 8. Stick to the Story
• 9. be Active: Why You should Avoid the Passive Voice and Weak Verbs
• 10. Diagrams, Lists and Graphics
• 11. Everybody Needs an Editor
• 12. the Technical Writing House of Horrors
• Afterword
• Index
• Back Cover