Technical Communication Today

Transcription

1 Technical Communication Today Richard Johnson-Sheehan Fourth Edition

2 Pearson Education Limited Edinburgh Gate Harlow Essex CM20 2JE England and Associated Companies throughout the world Visit us on the World Wide Web at: Pearson Education Limited 2014 All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without either the prior written permission of the publisher or a licence permitting restricted copying in the United Kingdom issued by the Copyright Licensing Agency Ltd, Saffron House, 6 10 Kirby Street, London EC1N 8TS. All trademarks used herein are the property of their respective owners. The use of any trademark in this text does not vest in the author or publisher any trademark ownership rights in such trademarks, nor does the use of such trademarks imply any affiliation with or endorsement of this book by such owners. ISBN 10: ISBN 13: British Library Cataloguing-in-Publication Data A catalogue record for this book is available from the British Library Printed in the United States of America

3 HELP On-Screen Documentation One of the major changes brought about by computers is the availability of on-screen documentation. Today, user s manuals and for products are often available through a website, provided on a CD-ROM, or included with the Help feature in a software package. The advantages of online documentation are numerous, and the disadvantages are few. The greatest advantage is reduced cost. After all, with some products like software, the accompanying user s manual costs more to print than the software itself. By putting the manual on a website, CD-ROM, or online Help, a company can save thousands of dollars almost immediately. Also, online documentation can be updated regularly to reflect changes in the product or revisions to the documentation. Companies are also putting specifications and procedures online, usually on the company s intranet. That way, all employees can use their computers to easily call up the documents they need. Several options are available for on-screen documentation: Online Help Increasingly, the online Help features that come with software packages are being used to present ( Figure A ). Online Help features Users can use the search function to find help on specific topics. The are listed here. A screen shot shows users how the screen will look. Online Help Figure A: Online Help features are another place where are commonly found, especially for software programs. These are from the online Help feature for Mozilla Firefox. Source: Mozilla Firefox, To learn more about on-screen documentation, go to 200

4 allow readers to access the more quickly, because they do not need to hunt around for the user s manual. As more documents move online, it is likely that will increasingly be offered as online Help. To write as online Help, you will need Help-authoring software like RoboHelp and Doc-to-Help, which simplifies the writing of Help features. CD-ROM Increasingly, computers have a CD burner as a standard feature. To make a CD, you can use web development software such as Adobe Dreamweaver or Microsoft Expression Web to create the files. Then, burn the files to a CD the same way you would save to a disk. Browser programs like Firefox, Safari, or Explorer will be able to read these multimedia documents. Website You can put your documentation on a website for use through the Internet or a company intranet. These files can be created with web development software such as Dreamweaver or Expression Web. Portable document format (PDF) Software programs such as Adobe Acrobat can turn your word-processing files into PDFs, which retain the formatting and color of the original document. PDFs can be read by almost any computer, and they store information efficiently. They can also be password protected so that readers cannot tamper with the text. PDFs can be placed on a website for easy downloading. Plain Style with a Touch of Emotion Documentation tends to be written in the plain style. Here are some suggestions for improving the style of your technical description: Use simple words and limit the amount of jargon. Define any words that might not be familiar to your readers. Keep sentences short, within breathing length. Use the command or imperative style (verb first) for any instructional steps. Keep it simple and don t over-explain basic steps or concepts. How can you further improve the style of your documentation? First, look at your original analysis of your readers and the contexts in which your document will be used. Pay attention to your readers needs, values, and attitudes. Then, try to identify the emotions and attitudes that shape how they will be reading and using the. Will they be enthusiastic, frustrated, happy, apprehensive, or excited? Identify a word that best reflects readers feelings as they are using your documentation. Then, use logical mapping to come up with some words that are associated with that word ( Figure 13 ). Want to know more about Help-authoring software? Go to 201

5 Mapping a Tone for Instructions impatient anxious eager glad happy pleased Figure 13: You can create an enthusiastic tone by finding synonyms associated with the word enthusiastic. ready delighted Enthusiastic excited pumped up energetic After you have found words that are associated with the appropriate tone, use them in the introduction, notes, and conclusion. These words, when used strategically, will reflect your readers attitudes or emotions. If your readers have a negative attitude (perhaps they are annoyed that they need to read ), you can use antonyms to counteract their feelings. For example, to soothe annoyed readers, use words like satisfy, pleasure, please, delight, and fulfill to counteract their negativity. Don t overuse them, though, because angry readers may detect your attempt to soothe them and feel like you are being patronizing. Functional, Attractive Page Layout The page layout of your documentation should be both functional and attractive, like the example in Figure 14. Here are some techniques that you might try: Incorporate graphics that illustrate and reinforce the written text. Try using a two- or three-column format that leaves room for graphics. Use boxes, borders, and lines to highlight important information, especially safety information. Use headings that clearly show the levels of information in the text. Worksheets to help you revise your are available at 202

6 If you are not sure how to design your, study sample texts from your home or workplace. You can use these examples as models for designing your own documentation. Graphics That Reinforce Written Text With computers, a variety of methods are available for you to add graphics to your documentation. You can add illustrations and diagrams (as in Figure 14 ). Or, you can use a digital camera or scanner to add graphics to your text. Here are some tips: Number and title your graphics, so readers can locate them. Refer to the graphics by number in the written steps. Put each graphic next to or below the step that refers to it. Place graphics on the same page as the step that refers to them. Check whether the graphics you have chosen could be misunderstood by or offensive to cross-cultural readers. Keep in mind that the graphics should reinforce, not replace, the written text. Design Is Important in Documentation Figure 14: In this unauthorized user s guide for the Cooper Mini, the use graphics to illustrate the text while making the information attractive. Images of people help users identify with the product. Source: 2006 MINI, a division of BMW of North America, LLC. All rights reserved. The MINI and BMW trademark and logo are registered trademarks. (continued) 203

7 Headings make the text easy to scan. Hazard statements are highlighted with an icon. Figure 14: (continued) Numbers and pointers highlight places discussed in text. Instructions are easy to find in this numbered list. For tips on laying out pages for documentation, go to 204