ebook img

Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation PDF

328 Pages·2009·4.99 MB·English
Save to my drive
Quick download
Download
Most books are stored in the elastic cloud where traffic is expensive. For this reason, we have a limit on daily download.

Preview Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation

To succeed in technical writing, you need 3rd Edition a lot more than just writing ability. covers Web 2.0 Technical Writing 101 details the skills you need as a technical writer to create both printed and online content. and DITA This valuable reference describes the entire development process—planning, writing, visual design, editing, indexing, and production. You also get tips on how to write information that is more easily translated into other languages. You’ll learn about the importance of following templates and about how structured authoring environments based on Extensible Markup Language (XML) streamline the content development process. This updated third edition features new information on the Darwin Information Typing Architecture (DITA) standard for structured authoring, and it explains the impact of A Real-World Guide Web 2.0 technologies—blogs, wikis, and forums—on to Planning and Writing technical communication. Technical Content by Scriptorium Press is the imprint of Scriptorium Publishing Services, Inc. PO Box 12761 Alan S. Pringle Research Triangle Park, NC 27709-2761 USA Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute. Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute. Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content Third edition Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Scriptorium Press, Scriptorium Publishing Services, and their logos are trademarks of Scriptorium Publishing Services, Inc. All other trademarks used herein are the properties of their respective owners and are used for identification purposes only. No part of this book may be reproduced or transmitted in any form or by any means, graphic, electronic, or mechanical, including photocopying, recording, tap- ing, or by any information storage or retrieval system, without written permission from Scriptorium Publishing Services, Inc. Part of Chapter 13 is adapted from Scriptorium Publishing’s white paper, “Struc- tured Authoring and XML,” which was originally published at www.scriptorium.com/structure.pdf. Chapter 14 is adapted from Scriptorium Publishing’s white paper, “Friend or Foe? Web 2.0 in Technical Communication,” which was originally published at www.scriptorium.com/whitepapers/web2/web2intc.pdf. Published by Scriptorium Press, the imprint of Scriptorium Publishing Services, Inc. For information, contact: Scriptorium Publishing Services, Inc. PO Box 12761 Research Triangle Park, NC 27709-2761 USA Attn: Scriptorium Press www.scriptorium.com/books About the authors Alan S. Pringle is director of publishing operations at Scriptorium Publishing Services, Inc. He implements new processes for developing and distributing technical content. His responsibilities include managing schedules and budgets for complex consulting projects, automating production and localization tasks with XML-based workflows, and working on large-scale DITA conversions. Alan guides books through the entire pub- lication process as the manager of Scriptorium’s publishing imprint, Scriptorium Press. Alan edited Publishing Fundamentals: Unstructured FrameMaker 8, Publishing Fundamentals: FrameMaker 7, and The WebWorks Publisher Cookbook. Sarah S. O’Keefe is president of Scriptorium Publish- ing. Since founding the company in 1996, Sarah has focused on efficiency—selecting the right publishing tools, creating templates, and training writers on how to use their tools. In 2002, she received her Certified Tech- nical Trainer (CTT+) accreditation from CompTIA. Her presentations at international, national, and regional conferences have consistently earned high ratings, and she is an Associate Fellow of the Society for Technical Communication (STC). Her publishing credits include Publishing Fundamentals: Unstructured FrameMaker 8, Publishing Fundamentals: FrameMaker 7 (originally pub- lished as FrameMaker 7: The Complete Reference), The WebWorks Publisher Cookbook, and numerous white papers. 5 Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute. About the authors 6 Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute. Acknowledgments Special thanks to the following people, who helped make this a better book: • Bill Burns for contributing to the chapter on local- ization and internationalization • Sean Byrne for drawing the illustrations • David Kelly for designing the cover • Larry Kunz for recommending updates in this edition • Sheila Loring for completing the final review • Terry Smith for reviewing the book and updating the index • The staff at Scriptorium Publishing for contributing to the section on DITA 7 Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute. Acknowledgments 8 Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute. Contents Preface 19 What’s in this book 19 Chapter 1: So, what’s a technical writer? 25 Knowledge of technology 26 Ignorance is bliss 28 Who treats the doctor and who documents for the writer? 29 Writing ability 29 Miss Thistlebottom was right… 30 Organizational skills 32 Strong detective (and people) skills 34 Chapter 2: The technical writing process 37 What you can expect (maybe) 37 Authoring with templates and with structure 40 Template-based authoring 41 Structured authoring 42 Are templates and structure really that important? 44 Templates and structure are good for your professional well-being 46 9 Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute. Contents Chapter 3: Very necessary evils—doc plans and outlines 47 What’s a doc plan? 48 Who writes the doc plan? 51 Any formulas for writing doc plans? 52 Outlining—it’s not just for high school papers anymore 54 What goes into the outline? 54 How many deliverables should there be? 56 Writing the outline 57 Chapter 4: The Tech Writer’s Toolbox 61 Content/text development tools for printed content 62 Graphics software and clip art packages 65 Rich media tools 66 Help or web authoring tools 67 File conversion and single-sourcing utilities 67 Other helpful software 69 Computers and ergonomics 70 Chapter 5: Getting information 73 Technical specifications and other development content 74 The benefits of a spec 74 The drawbacks of a spec 75 Prototypes and software under development 76 The benefits of prototypes and prerelease software 78 The drawbacks of prototypes and prerelease software 79 Legacy content 81 The benefits of legacy content 81 The drawbacks of legacy content 81 10 Copyright © 2000–2009 Scriptorium Publishing Services, Inc. Please do not share or redistribute.

See more

The list of books you might like

Most books are stored in the elastic cloud where traffic is expensive. For this reason, we have a limit on daily download.