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

328 Pages·2009·4.99 MB·English

by  Alan S. Pringle

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.