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

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

Softcover

ISBN 10: 0970473303 ISBN 13: 9780970473301

Publisher: Scriptorium Pr, 2000

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. You'll appreciate the tips on getting a job as a technical writer, whether you re considering technical writing as your first job or as a career change.

About this title

About the Author

Sarah S. O’Keefe is founder and president of Scriptorium Publishing Services, Inc., which provides technical documentation services to high-tech companies, including everything from start-ups to Fortune 100 companies. Sarah is an Adobe Certified Expert in FrameMaker and certified WebWorks Publisher trainer. Her background includes technical writing, technical editing, production editing, and extensive online help development with various help authoring tools. Sarah is the author of FrameMaker for Dummies. She currently works as a consultant to assist companies in implementing single-sourcing systems and other publishing solutions.

Alan S. Pringle is lead technical editor at Scriptorium Publishing Services. 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 completed large HTML conversion projects.

Excerpt. © Reprinted by permission. All rights reserved.

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 a technical writer does and what skills might make technical writing a good choice for you.

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 some 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, and perhaps we ll be able to convince you 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, including addressing a document s audience and dividing 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.

The appendices provide information about how to get a job, along with lists of resources 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, and Appendix C, Tools information

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

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: 2000
• Language: English
• ISBN 10: 0970473303
• ISBN 13: 9780970473301
• Binding: Paperback
• Edition number: 1
• Number of pages: 258