Guides to Professional English Series Editor: Adrian Wallwork Pisa, Italy For further volumes: http://www.springer.com/series/13345 Adrian Wallwork User Guides, Manuals, and Technical Writing A Guide to Professional English 1 3 Adrian Wallwork Pisa Italy ISBN 978-1-4939-0640-6 ISBN 978-1-4939-0641-3 (eBook) DOI 10.1007/978-1-4939-0641-3 Springer New York Heidelberg Dordrecht London Library of Congress Control Number: 2014939424 © Springer Science+Business Media New York 2014 This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illus- trations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed. Exempted from this legal reservation are brief excerpts in connection with reviews or scholarly analysis or material supplied specifically for the purpose of being entered and executed on a computer system, for exclusive use by the purchaser of the work. Duplication of this publication or parts thereof is permitted only under the provisions of the Copyright Law of the Publisher’s location, in its current version, and permission for use must always be obtained from Springer. Permissions for use may be obtained through RightsLink at the Copyright Clearance Center. Violations are liable to prosecution under the respective Copyright Law. The use of general descriptive names, registered names, trademarks, service marks, etc. in this publication does not imply, even in the absence of a specific statement, that such names are exempt from the relevant protective laws and regulations and therefore free for general use. While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsi- bility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein. Printed on acid-free paper Springer is part of Springer Science+Business Media (www.springer.com) Introduction for the reader Who is this book for? This book is intended for anyone whose job involves writing formal documentation (e.g. user manuals, technical reports, RFQs). It is aimed at non-native speakers of English, but should also be of use for native speakers who have no training in technical writing. Technical writing is a skill that you can learn and this book outlines some simple ideas for writing clear documentation that will reflect well on your company, its image and its brand. The focus of the book is thus on writing skills: it does not cover issues of layout and graphics. Most of the rules / guidelines contained in this book are not exclusive to English, and can be applied to documentation in any language. What are the typical difficulties of writing company documentation? What is the focus of this book? The main issues are: 1. knowing who your readers are: their level of prior knowledge and the expectations they have while reading your document 2. using a consistent layout, format and style 3. writing clearly and concisely with no ambiguity This book is part of series of books on using the English language at work. It thus focuses on the third point above. However, being able to write clearly and concisely with no ambiguity also implies incorporating the other two points as well. v vi What are the differences between technical writing and other kinds of writing? This book covers technical writing. However, most of the rules and guidelines given are equally applicable to reports, emails, presentations and other kinds of formal company documentation. The aim of all these documents is to be as clear as possible and thus enable the reader to assimilate the information in the least time possible. This kind of writing differs massively from the way you were probably taught to write at school, where long sentences and an abundance of synonyms were probably considered signs of good writing. But you will have no problem in quickly understanding the benefit of writing in short simple sentences that contain no redundant words and are unambiguous. Remember you are writing to inform. You are not writing to impress a teacher or your boss. All documents that you produce for your company are a reflection of the company’s brand and image. Mistakes indicate a lack of professionalism behind the document, and thus the company in general. For example, misspelling of a client’s name or of your own products reflects badly on the whole company. When users buy a product, most will know what the product is. What they really want to know is how to use to it, rather than read a description of what it is. This means that you need to: • find out who your readers will be and how they going to use your document. This also means discovering if there will be different types of readers (managers, technical staff, end users) and adjusting the style accordingly • ascertain what prior information and knowledge your readers have. Then decide what they need to know and give them only that. At the same time, avoid making assumptions. Unless you know the reader, you can’t be sure that their knowledge of the subject is as advanced as yours • get your ideas clear in your mind. If you’re not sure exactly what it is you’re writing about, then how can you expect your readers to understand? So, write a plan. Get everything into its logical order • for all types of readers, the document must be easy to understand quickly and it should be an enjoyable process for them – they get what they want with minimal effort vii • make your guide predictable. Readers should intuitively be able find what they want easily and quickly. The whole guide should be presented in the same way throughout. For example, procedures should always be described in the same pattern – a series of steps with the outcome clearly given at the end • ensure that all documents of a similar nature look the same. Readers can thus learn how to use them. So the next time they receive a technical document from your company, they will know where to find everything The result will be that reader’s expectations are met. They won’t get tired or frustrated reading your document. Your aim is to use up as little of your reader’s time as possible. People don’t read company documents (manuals, reports etc) for fun, so you need to make the act of reading your documents a satisfying experience. Bear in mind that people consult a user manual as a last resort. They are unable to solve the problem by themselves, so they look at the manual for help. When they read the manual they may be stressed or angry, so they need to find a solution in the quickest time possible. Finally, remember that a user manual is not a piece of sales literature. Below is an extract from the Introduction to a medical device for home use. Congratulations on your choice of XXX for safe, effective pain relief…. You will soon wonder how you ever managed without your XXX. Such sentences rarely add value for users as they have already bought the product and so do not need further convincing. Limit such usage to an advertisement. viii How is this book organized? How should I read the book? The book is organized into three parts. Part 1 structure and content This gives details about the typical sections found in a user manual and the order they are usually found in. Through examples, you will learn best practices in writing the various sections of a manual and what content to include. Part 2 clear unambiguous english This gives guidelines on how to write short clear sentences and paragraphs whose meaning will be immediately clear to the reader with no ambiguity. Part 3 layout and order of information Here you will find guidelines to issues of style such as the use of headings, bullets, punctuation and capitalization. Part 4 tyPical mistakes This section is divided alphabetically covering grammatical and vocabulary issues that are typical of user manuals. Before drafting your first manual, I suggest you read Parts 1 and 2 carefully. Then read the contents page of Parts 3 and 4, and check if there any points that you are not clear about. All the examples given have been adapted from real manuals and brochures. How are the examples presented? Examples are shown in two ways in this book: 1. Indented and in a smaller narrower font. 2. In a table with YES and NO headings. For examples of type 1), I will tell you whether the use of bold and italics is for the purposes of the book (i.e. to highlight particular usages or mistakes) or whether bold and italics were part of the formatting of the example in its original location. For examples of type 2), all cases of bold are to highlight particular usages or mistakes. ix Where do the examples in this book come from? The examples in Part 1 have been adapted from a wide range of guides, instruction manuals and company literature for the following: a powered golf trolley, software for trading on electronic money markets, a steam iron, a tumble dryer, an electric oven, a washing machine, an intra- sonic pain relieving device, a digibox, personal banking literature, and a supercharger. The examples in the rest of the book either come from software manuals or were invented for the purposes of this book. The invented sentences are examples in general English which are used to show how grammatical rules are applied and certain vocabulary terms are used. We are not native English speakers. Is it worth getting a professional (native English-speaking) technical writer to look at our documents? Yes. Even if you can’t employ a technical writer on your staff, you can at least use their services whenever you draft a new kind of document. A technical writer will not only check the grammar, language, punctuation, and spelling of your documents but will also: • suggest a style (formatting, pagination) for your company’s docs • follow international guidelines on writing documentation (e.g. the Chicago Manual of Style) • rewrite in order to clearly communicate what the author has in mind • restructure, where appropriate, the order in which information is given • tailor information to the knowledge level of the audience • apply a “one word – one meaning” approach • ensure clarity for multi-national English readers / speakers • ensure that product names are written correctly (names, spelling, capitalization) • have discussions with authors to enhance understanding and clarity • check any legal notices e.g. copyright info and trademark acknowledge- ments x Terminology and abbreviations used in this book doc document info information you the person reading this book and thus the writer of company documents product the product or service described in a user manual user the reader of a user manual user manual a technical document intended to help user’s use a product or service. Also known as a ‘user guide’ Other books in this series There are currently five other books in this Professional English series. CVs, Resumes, and LinkedIn http://www.springer.com/978-1-4939-0646-8/ Email and Commercial Correspondence http://www.springer.com/978-1-4939-0634-5/ Meetings, Negotiations, and Socializing http://www.springer.com/978-1-4939-0631-4/ Presentations, Demos, and Training Sessions http://www.springer.com/978-1-4939-0643-7/ Telephone and Helpdesk Skills http://www.springer.com/978-1-4939-0637-6/ All the above books are intended for people working in industry rather than academia. The only exception is CVs, Resumes, Cover Letters and LinkedIn, which is aimed at both people in industry and academia. There is also a parallel series of books covering similar skills for those in academia: English for Presentations at International Conferences http://www.springer.com/978-1-4419-6590-5/ English for Writing Research Papers http://www.springer.com/978-1-4419-7921-6/ English for Academic Correspondence and Socializing http://www.springer.com/978-1-4419-9400-4/ English for Research: Usage, Style, and Grammar http://www.springer.com/978-1-4614-1592-3/