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

Pringle, Alan S.; O'Keefe, Sarah S.

Softcover

ISBN 10: 097047332X ISBN 13: 9780970473325

Publisher: Scriptorium Pr, 2003

Synopsis

To succeed in technical writing, you need a lot more than just writing ability. Technical Writing 101 details the skills you need as a technical writer, and it explains how to handle the pressures of tight deadlines and ever-changing product specifications. This valuable reference also describes the entire documentation process—planning, writing, editing, indexing, and production.

This updated second edition features the latest information on single sourcing and a new chapter on how trends in structured authoring and Extensible Markup Language (XML) affect technical writers.

About this title

About the Author

Alan S. Pringle is lead technical editor at Scriptorium Publishing Services, Inc., and director of its publishing imprint, Scriptorium Press. The company provides technical publishing services to high-tech companies, including outsourced documentation solutions, technical training, and consulting. Since 1990, he has worked as a technical writer and editor on projects ranging from writing user guides for laser printers to editing course material for telecommunications equipment. Alan has also established corporate style guidelines and implemented XML-based structured applications for FrameMaker workflows. He is coauthor of the FrameMaker 7 Workbook Series.

Sarah S. O’Keefe is founder and president of Scriptorium Publishing Services, Inc. Sarah is an experienced FrameMaker trainer; she has both Certified Technical Trainer (CTT) and FrameMaker Adobe Certified Expert (ACE) credentials. Her background also includes technical writing, technical editing, production editing, and extensive online help development with various help authoring tools. Sarah is coauthor of FrameMaker 7: The Complete Reference. Currently, she works as a consultant to assist companies in implementing publishing solutions, including XML-based structured authoring.

Excerpt. © Reprinted by permission. All rights reserved.

Preface

For technical writers, answering the obligatory "What do you do for a living?" question at a party can have many effects. It can:

* Create more questions: "What's that?"

* Draw blank stares

* Provoke some minor hostilities: "Did you write that worthless manual that came with my word processing software? That book reeked!"

So, if you've decided that you want a career in technical communication, be prepared. Although you'll have a challenging, fast-paced job that changes as swiftly as the technology you write about, discussing your work at a party will be quite a conversation stopper.

What s in this book

Technical Writing 101 will show you that there's more to technical writing than just writing. The first major section of the book explains the skills you need as a writer. It also describes some of the essential tools and techniques for delivering projects on schedule and on budget. The chapters in this section are:

* Chapter 1, "So, what's a technical writer?"

Explains what technical writers do and what skills they need.

* Chapter 2, "An overview of the technical writing process"

Provides a high-level view of the technical writing process. Most documentation projects share a common structure even when the subject matter is completely different.

* Chapter 3, "Very necessary evils doc plans and outlines"

Explains two project management tools that every technical writer needs. Documentation plans provide writers with a roadmap to follow as they create materials. Typically, a documentation plan includes a description of the target audience, the schedule, and a list of documents or online help to be developed. Manual outlines are just that those hideous indented things you probably remember from high school. Unfortunately, you'll discover that outlines are in fact a necessity for technical writers, but perhaps you'll be convinced that they aren't so bad when you're trying to write an entire book!

* Chapter 4, "The Tech Writer's Toolbox"

Focuses on the tools and technologies that you need to work successfully. Technical writers use a variety of writing and graphics packages to develop material.

In the second major section, you learn about how to get information, organize information, and (finally) write documentation. The chapters also describe other tasks in the documentation process, such as creating graphics, technical editing, production editing, and indexing. The chapters in this section are:

* Chapter 5, "Getting information"

Gives you tips on how to extract information from source documents and product developers. Many people respond well to bribery, especially when the bribe is edible and includes chocolate in some form.

* Chapter 6, "Finally it's time to start writing"

Describes how to write documentation. When writing, it's important to address the document's audience and to divide your content into different types of information interface, reference, conceptual, and procedural.

* Chapter 7, "Writing task-oriented information"

Explains the basics of writing procedures. Because most technical documents tell users how to perform tasks, the ability to write good task-oriented information is a fundamental skill for all technical writers.

* Chapter 8, "A few words about pictures"

Describes how to create and work with images. A graphic may not be worth exactly a thousand words, but an illustration can often explain something with more clarity than any amount of text.

* Chapter 9, "Editors resistance is futile"

Explains what you can expect from an editor and what most editors can expect from you. Refusing to work with an editor is not an option for technical writers editing is an essential component of the technical documentation process. A competent editor can make you look good by catching your mistakes before the client sees them.

* Chapter 10, "Indexing"

Explains the basics of writing a good index. A thorough, useful index is essential because readers often check the index first when looking for a particular piece of information. A good index can also save a company money readers who quickly find the information they need are less likely to call customer support.

* Chapter 11, "Final preparation production editing"

Tells you how to make sure your document is ready for printing by checking for line breaks, page breaks, and other formatting issues.

The third section explains some advanced topics. Chapters in this section are:

* Chapter 12, "Avoiding international irritation"

Offers some tips on minimizing the hassles that occur when documentation is translated into other languages. Learning about the translation process before you start writing the English documentation can save your company a lot of time and money and prevent many, many headaches.

* Chapter 13, "Single sourcing"

Describes how to create multiple types of deliverables hardcopy books and online help, for example from one set of files. The ability to create multiple deliverables while minimizing the time and money spent is important for many documentation departments, which often operate under tight schedules and with limited budgets.

* Chapter 14, "Structured authoring with XML the next big thing"

Explains the new trend of implementing structured authoring a publishing workflow that defines and enforces consistent organization of information in documents and how it affects technical writers.

The appendices provide information about getting a job, lists of resources and tools, and a sample documentation plan. The appendices are:

* Appendix A, "Getting your first job as a technical writer"

Gives you some pointers on tailoring your resume for technical writing jobs, interviewing, and putting together a portfolio.

* Appendix B, "Resources"

Lists web sites, books, and organizations that are useful for technical writers.

* Appendix C, "Tools information"

Lists tools technical writers use.

* Appendix D, "Sample doc plan"

Contains a sample documentation plan.

This book focuses on documentation for computer hardware and software. However, many of the concepts described apply to other forms of technical writing, such as writing about manufacturing environments, medical and pharmaceutical topics, and science.

If you're a talented writer with an interest in technical topics, writing technical documentation can be quite lucrative. This book gives you the advice and tools you'll need to get started in this challenging field.

Edition details

• Publisher: Scriptorium Pr
• Publication date: 2003
• Language: English
• ISBN 10: 097047332X
• ISBN 13: 9780970473325
• Binding: Paperback
• Number of pages: 288