eBook
Available on Compatible NOOK devices, the free NOOK App and in My Digital Library.
Related collections and offers
Overview
Product Details
| ISBN-13: | 9781780174488 |
|---|---|
| Publisher: | BCS, The Chartered Institute for IT |
| Publication date: | 09/06/2018 |
| Sold by: | Barnes & Noble |
| Format: | eBook |
| Pages: | 70 |
| File size: | 1 MB |
About the Author
Read an Excerpt
CHAPTER 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.
CHAPTER 2SEVEN 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. delivery;
6. evaluation and feedback;
7. revision, archiving or destruction.
Let's explore each section in turn. We'll also look at a few general considerations for a technical writing project too.
1. SPECIFICATION, AUDIENCE AND SCOPE
The first part of any technical writing project is to identify the who, the what and the why. Who are you writing for? What information do they need? Why and where do they need it? These pieces of information are crucial. If you don't know who you're writing for, you can't know how best to communicate, what level of knowledge or expertise you can expect them to have or what the best medium for communicating with them would be. An airplane safety card isn't much use if it's in a language the passenger doesn't understand.
2. PLANNING
Good technical writing takes time. Once you've identified the who, what and why, you need to plan out the how, the where and the when. How should this information be delivered? What resources do you need in order to do it properly? What is the best medium for the message you're communicating and how should the message be structured? When does it need to be delivered? How is it going to be tested and reviewed?
3. RESEARCH AND WRITING
For many of us this is the easy, fun bit. It's described very well in the parable of the engineer and the hammer. If you don't know it, it goes something like this.
One day, a factory's most important machine breaks down at the worst possible time. Already losing money at a frightening rate and unable to get the machine going again, the company has no choice but to call in a very experienced and very expensive engineer. He strolls in, pulls out a hammer and whacks the machine very hard, just once. The machine immediately bursts into life and the engineer hands the manager an invoice for £10,000.
The manager is outraged. Ten grand for hitting a machine once? That's daylight robbery! He demands the engineer account for the charge and demands an itemised invoice with a full breakdown of the engineer's fees.
The engineer agrees. The following day, a new invoice arrives and this time it's itemised.
Hammer: £5;
Knowing the right place to hit with a hammer: £9,995.
This part of the technical writing process is your £5 hammer because with a good specification, the right resources and a solid plan you're just typing here. The real value comes from what you do before and after you actually write, and from the knowledge and experience you bring to the project.
4. TESTING, REVIEWING AND REVISION
This section is as important as the actual research and writing. It's when you discover what other people do with your documents, and it's often an eye-opener: if you've assumed too little or too much knowledge on your readers' part that will soon become glaringly obvious, as will any major omissions or mistakes. It's really important to put your ego aside during this part of the process as your goal is to create the best possible end product with the resources, time and budget available to you. Criticism and highlighting errors helps you achieve that.
5. DELIVERY
Delivering the finished product isn't the end; it's the end of the beginning. It's a good time to give yourself a pat on the back for a job well done, but it's a job you'll normally return to.
6. EVALUATION AND FEEDBACK
Issues or problems with technical writing don't always appear during the testing and revision stage. Sometimes the writing needs to be used in real-world situations in order for any flaws to become apparent. And that's okay, because you've already thought about that and ensured that your readers can and will provide feedback in a form that you can use to refine the job, solve any problems and polish it to perfection. This is also the stage where localisation would take place if necessary; for example, if your material needs to be rewritten for another language, market or audience.
7. REVISION, ARCHIVING OR DESTRUCTION
Many technical documents have a limited lifespan: hardware, software or systems change; legislation is repealed or reformed; mission creep may mean that a particular system's role becomes much wider than initially imagined. That means documentation needs to be under constant review: updated where appropriate, retired when no longer necessary, destroyed if it contains secrets that shouldn't be revealed.
In this book our focus will be on the research and writing stage: the knowing which bit to hit with our hammer.
TECHNICAL WRITING IN A TEAM
Some technical writing jobs are too big for one person to do without help. If you're going to be writing as part of a technical writing team, it's crucial to have somebody in charge of the whole project. That person may well be you.
The person in charge of a technical writing team is effectively a project manager. Their job is to allocate different parts of the project to different people, to ensure that those parts are done correctly and on time, and to ensure consistency across the entire project. It's a job that begins at the very early planning stages and continues through publication and review.
A QUICK WORD ABOUT WRITING APPS
For a technical writing project, you don't need a dedicated writing app if you've got access to Microsoft Word, Apple Pages, Google Docs, OpenOffice or other Office-style software, and, of course, you can write effectively with nothing more than a notepad and a Biro.
However, if you're going to be doing a lot of technical writing it's worth considering a writer-specific app such as Scrivener, which is available for Windows, Mac and iOS. It isn't expensive – at the time of writing it's around £33 for computers and £20 for iOS devices – and it'll pay for itself many times over. It's particularly useful for large projects and for projects that will be published in multiple formats both in print and online.
In a team-based writing environment, your priorities may be slightly different: you can of course use whatever writing app you prefer, but when it comes to collaborating with others then you're making life unnecessarily difficult if you don't use a platform with instant, effortless collaboration and communication tools.
You're probably familiar with email tennis, when the same file or files are constantly moving backwards and forwards between relevant people who add their comments or changes. Staying on top of that can be very difficult, and it's easy to end up with people receiving documents that have since been updated or making comments that others have already made. A good online service such as Office 365, Google Docs or iCloud prevents that from happening by giving everybody the most up-to-date version of the document.
You might also find that your favourite writing app works with third party sharing and collaboration services, so, for example, if you use Scrivener, you can synchronise your documents with the cloud-based storage and synchronisation service Dropbox, so that people without Scrivener can open, edit and comment on them. Dropbox and its rivals also offer online collaboration tools that you can use without having to go through Scrivener first.
There are two key features you may need for online collaboration: commenting and change tracking. The former enables relevant parties to add notes to the text without actually changing it – suggestions or links to other things to include, perhaps, or questions about particular bits – and for you to respond or mark comments as resolved. And the second feature, change tracking, enables you to see exactly what changes others have made and to accept or reject those changes as appropriate.
Many apps enable you to set different levels of access for different people or groups, so you might give other members of your team full edit access but limit non-writers' access to commenting and highlighting only.
You don't necessarily need to be using the same apps to collaborate. Microsoft Office's commenting and change tracking works in some other apps, so a .docx file from Word should still include its comments and change tracking if you open it in Apple's Pages (and remember to export it in .docx format to preserve the tracking information).
A QUICK WORD ABOUT FORMATTING TEXT
When you're writing, it's a very good idea to use as little text formatting as possible. That's particularly true if you're going to be writing for multiple platforms, such as printed documentation and online systems such as CMSs: what looks good as a Word document may require extensive editing if you paste it into a CMS that uses different formatting options.
In the past I wrote everything and stored it as plain text (.txt) documents without any formatting whatsoever, but in recent years I've become a convert to Markdown. Markdown is supported by a huge range of writing apps, and it's designed to make creating and reusing formatted text easy.
It does that with simple shortcuts, so, for example, if I want to format a bit of text as a heading, I put a single hash in front of it. Two hashes means heading 2, three means heading 3 and so on. Other shortcuts enable me to add bullet points or numbered lists, hyperlinks or blocks of code. The documents are all stored as plain text files, but Markdown-aware writing apps can export in a range of unformatted and formatted file types such as Microsoft Word, PDF, rich text format, ePub and so on. All you need to do is choose the format and template you want to use, and your writing app will create the appropriate file.
It's the same write-once run-anywhere approach you see in web design, where page content (the XHTML file) is separated from the formatting (the relevant style sheet); changing the style sheet (or the template, in my writing app), changes the formatting without having to go through the document and replacing every formatting option.
(Continues…)
Excerpted from "Technical Writing for Business People"
by .
Copyright © 2018 BCS Learning & Development Ltd.
Excerpted by permission of BCS The Chartered Institute for IT.
All rights reserved. No part of this excerpt may be reproduced or reprinted without permission in writing from the publisher.
Excerpts are provided by Dial-A-Book Inc. solely for the personal use of visitors to this web site.
Table of Contents
- What is Technical Writing?
- Seven Steps to Heaven: The Technical Writing Cycle
- Know Your Audience
- Break It Down: The Importance of a Task-Based Approach
- Assume Nothing
- Vanquish Vagueness
- Don't Be Yourself
- Stick To The Story
- Be Active: Why You Should Avoid The Passive Voice and Weak Verbs
- Diagrams, Lists and Graphics
- Everybody Needs An Editor
- The Technical Writing House of Horrors