https://DevOpsCloud.io -- Cloud Monk Losang Jinpa

Return to Insider's Guide to Technical Writing, Technical Writing, Technical Writing Bibliography, Writing Bibliography, Writing, Writing Topics, Awesome Tech Writing

Fair Use Source: B09X2CHHB1 (InGdTecWrt 2022)

“Starting as a technical writer in 2012 is so different from starting in 2001, when Krista Van Laan’s first book was published. It’s even more different since I started in this field in 1977. I’m pleased that Krista has written a new version of her first guide for technical writers. Not only has Krista brought the technology up to date, but she has also stressed what professional technical writers have known for 30 years and more: the importance of knowing your information users and their needs and knowing them better than anyone else in the organization.

Not only should the user be the center of the technical writer’s world, but first-rate technical writers must be responsible for understanding the product. Too often, as I’m sure we’ve all experienced, it seems as if whoever has written the user guide has never actually used the product. That crucial small insight that makes the difference between a successful instruction and one that is confusing and frustrating only comes from direct experience and lots of communication with real users. As Krista emphasizes from the very first, writers need to get out of their cubicles and meet the users.

The Insider’s Guide provides exactly the perspective that new technical writers need about teamwork, collaboration, responsibility, curiosity, and more. At the same time, it describes what managers expect today from their writers, even writers with multiple years of experience. The emphasis on flexibility and a willingness to change with the environment is an essential feature of this book.

In Part 1: “Is This the Job for Me?” the advice for people seeking to enter the field is remarkably sound. Education, training, internships, networking, and social media all provide avenues for newcomers to the field. Following the recommendations in Part 2: “Building the Foundation” provides a newcomer with a path to success in finding a job opportunity.

A newcomer on a first assignment is well served by the recommended best practices, especially the focus on knowing the user and knowing the technology. No one should come away from The Insider’s Guide believing that technical writers are simply formatters of other people’s words. In fact, I recommend giving copies to colleagues in engineering, software development, and management who might not understand what the technical writer’s role should be. Part 2 makes the best practices of this field clear, demonstrating what good technical writing looks like and how it comes to be.

Part 3: “The Best Laid Plans” begins with the need for planning—from my point of view, an essential recommendation. Too often new writers just start writing without any idea of where they are going or how long it will take. Especially important is Krista’s advice to become your own subject matter expert. It’s a mistake to think that engineers and software developers will write the content for you. First, they have their own jobs to do. Second, they are unlikely to keep the end users’ point of view in mind as they write. That, of course, is your job.

Part 4: “On the Job” focuses on the information a new writer needs about the day-by-day project requirements. I’m particularly pleased with the focus on topic-based writing, especially the Darwin Information Typing Architecture (DITA) standard. Even if you are in an organization that continues to produce books in print or PDF, thinking and writing in topics is an essential perspective. Consider that the topics that you now might compile into a book can easily be transformed in the future into context-sensitive help topics or individual articles on a website, in social media, or on a mobile device.

In Part 5: “The Tech Writer Toolkit,” Krista carefully sums up the essentials of the trade. Discussions of style guides, front and back matter, indexes and glossaries, and typography provide a complete toolkit. I’m happy to note the emphasis on writing for translation and understanding the localization process. Writers must be aware of the problems they can cause translators and how to avoid them.

Finally, in Part 6: “I Love My Job…” it’s good to hear about the negatives of the field—as a dose of reality.

For many years, experts in the field have collected data that demonstrates the value of sound, usable information on customer satisfaction. We link that satisfaction to improved customer loyalty to a product and a brand. Successful users, happy with products they know how to use, become loyal customers, recommending a product to friends and colleagues as well as investing more for their own use.” (InGdTecWrt 2022)

JoAnn T. Hackos, Ph.D.

President, Comtech Services

JoAnn Hackos is president of Comtech Services, a content-management and information-design firm based in Denver, Colorado. She is director of the Center for Information-Development Management (CIDM), and a founder of the OASIS DITA (Darwin Information Typing Architecture) Technical Committee and an author of the DITA specification. She is a past president and Fellow of the Society for Technical Communication. Her books include Introduction to DITA: A User Guide to the Darwin Information Typing Architecture; Information Development: Managing Your Documentation Projects, Portfolio, and People; Content Management for Dynamic Web Delivery; Managing Your Documentation Projects; Standards for Online Communication; co-author of User and Task Analysis for Interface Design.

“I published my first book about technical writing, The Complete Idiot’s Guide to Technical Writing (Alpha Books) in 2001 with co-author Catherine Julian. That book was written and published during a very fertile period for technical writers. The “dot-com” bubble was at its biggest. Many high-tech companies that are now household names got their start during that time, and all of those companies discovered that they needed technical writers. A book that explained how to do the job was a great help, not only to newcomers in the field, but also to old-timers who were learning how to do things they’d never done before.

Technical writers today wear even more hats than they did then. Today’s tech writers truly are technical communicators, as they build information to be distributed in many forms. A book that explains the big picture is more useful than ever for the tech writer who strives to add value to the company.

As well, the technology has changed so drastically that a book published in 2001 has very little application in the world of today’s technical writer. That is why I’ve written this book for today’s world and today’s technical writer, the technical writer who’s not an idiot, but rather a smart and ambitious person who wants to learn about the profession from someone who knows it from the inside out. While some material is repeated and updated, nearly all of it is new, so even people who read both will find completely new and useful material in The Insider’s Guide to Technical Writing.

This book is targeted to technical writers at many levels: those of you who are interested in the field and want to learn more about it, and those of you who are just starting out in the field and want to be the best you can be on the job. It also contains much information for experienced technical writers, many of whom would like to know about tools and technology they may not be currently using. If you are a lone technical writer, you are sure to find useful information in this book as you wonder, without colleagues to brainstorm with, how to do something different or better. Finally, I believe this book has value for the beginning Technical Publications manager. Managers need to know about much more than just writing, and this book covers the entire technical writer’s toolkit.

I’ve worked in, managed, and built from the ground up multi-level Technical Publications and User Experience departments in telecommunications, consumer software and hardware, enterprise software and services, and Internet companies. I’ve used tools you’ve never heard of and ones you’ll use daily, and written every type of content there is as an employee, contractor, and freelancer. I’ve trained beginners with no more skills than the ability to write in English, who then became highly skilled technical writers. And I’ve had documentation managers report to me as well, so I’m able to provide information that will help a Tech Pubs manager build and run a better group.

This is the book I wish I’d had when I was starting out and when I was training beginners—a resource that not only tells you how to follow best practices of technical writing (there are lots of those), but also provides specific steps on how to master the non-writing skills that are so important to daily work life—skills like scoping time lines, setting benchmarks, shepherding reviewers, and coping with products still evolving until the day they ship. It’s a book that can get you through a major, daunting transition—starting from zero and climbing to a high level of professional competence and confidence. A book about the job of being a technical writer.

My experience is largely in high tech, and that environment is the focus of this book, even though technical writing is needed in many other work environments. I believe that if you can succeed in the high-tech world, you can manage anywhere. Although the examples given in this book apply to software, hardware, and website writing, the rules, best practices, and methodology of technical writing can be applied to any field.

Of course, there is still much more that could go into this book. I think of new topics I could have added all the time, and you will, too. You’ll find a better way to do something or hear of a different tool or process to use that didn’t get mentioned in this book. But I feel confident that with the foundation this book provides, you’ll know how to seek more information about the things that interest you, and more importantly, try them out yourself. You won’t be in the dark when someone drops a buzzword or mentions an aspect of technical writing that you might not otherwise have heard of.

I’m keeping no secrets here. I’ve laid out all I know about what it takes to work as a well-rounded and successful technical writer—the kind of writer who gains respect from colleagues all across a company.

If you want a career that lets you play with all kinds of fun technology, interact with smart and creative people, put the keys to high-tech products into the hands of users, and earn a good living by writing, then this book can help you find your way. Whether or not the market is booming, the technical writing profession always has a steady beat!” (InGdTecWrt 2022)

Krista Van Laan

San Jose, California

April 2012

Fair Use Sources:

• Insider's Guide to Technical Writing on DuckDuckGo
• B09X2CHHB1 (InGdTecWrt 2022)