Managing Writers

A Real World Guide to Managing Technical Documentation

Richard Hamilton

• Publisher: XML Press
• Year: 2009
• Print ISBN: 9780982219102
• eBook ISBN: 9781457182266
• Edition: 1
• Topic: Computer Science
• Subtopic: Project Management
• Index: Computer Science

Managing Writers is a practical guide to managing documentation projects in the real world. It is informal, but concise, using examples from the author's experience working with and managing technical writers. It looks beyond big project, big team methodologies to the issues faced by smaller, less well-funded projects.

Managing Writers is for technical writers, both freelancers and employees, documentation managers, and managers in other disciplines who are responsible for documentation; anyone who may need to manage, full or part-time, a documentation project.

Inside the Book

• Leading People
• Leading Projects
• Leading Technology
• Glossary, Bibliography, and Index

Managing Writers

A Real World Guide to Managing Technical Documentation

Richard L. Hamilton

To Mei-li

Preface

When I started working as a documentation manager, common “wisdom” was that anyone could manage technical documentation. I had no experience with documentation or management, and no one, except possibly the people I was to manage, thought that would be a problem. As I soon discovered, managing documentation takes a broader set of skills than most engineering management jobs. Where else would you find yourself managing a team that included a carpenter, electrical engineer, English major, psychologist, and mathematician, all working together on software documentation? That is not a random assortment; that is the range of skills on just one of the documentation teams I have managed.

In addition to being able to manage a diverse team, a documentation manager must have a strong technical background, both to understand the technology being documented and to understand the technology behind the tools being used by the documentation team.

If that is not enough of a challenge, consider that technical documentation lives at the intersection of two disciplines, engineering and communicating, which are the oil and water of the business world. You and your writers need to bridge that gap internally, with engineers, and externally, with customers.

Most important, technical documentation is viewed with disdain by many engineers and lives at the bottom of the power hierarchy in most companies. A significant amount of your time as a documentation manager will be spent working to gain respect, power, and leverage so you can do your job.

These factors make managing technical documentation challenging and frustrating, but also rewarding. Documentation has broadened from a discipline focused on writing books to one that communicates through words, graphics, audio and video, in media from paper to help systems to web sites to podcasts and beyond. Despite the perception that “no one reads the documentation,” the right documentation in the right form can make the difference between a product that works and one that does not.

This book covers the basics of managing a documentation team, including hiring, motivating, and planning, and it goes beyond the basics to look at the things that make this discipline unique. My objective is to give you the information you need to successfully manage documentation people, projects, and technology.

1. Audience

This book is for anyone, regardless of title, who manages technical documentation projects or people. In addition to those who hold the title “Documentation Manager,” this includes:

• Writers who manage their own work or the work of others. In a down-sized world it is common for writers to be expected to manage themselves and their schedules. This book will help you plan your projects better and be more effective working with your engineering teams.
• Product development or marketing managers who have one or more writers on their team. Even if you delegate a lot of the management job to those writers, this book will help you understand their challenges and be supportive of their needs.

2. Structure

The book has four major parts: Getting Started, Managing People, Managing Projects, and Managing Technology.

Getting Started introduces the book. Chapter 2: The Elements of Technical Writing covers the essential elements of technical documentation from the writer's perspective. Chapter 3: Power and Influence discusses the central struggle for documentation managers, power.

Managing People discusses motivation, change management, performance evaluation, hiring, and human resources. Despite the existence of references in all of these areas, many managers start their careers woefully ignorant of how to manage people. In addition to looking at the basics of good people management, I also look at some of the things that make managing technical communicators a unique challenge.

Managing Projects discusses development methodologies, project planning, estimation, tracking, and localization. Managing technical documentation projects shares some characteristics with managing projects in other disciplines, but it also offers unique challenges. Most of these challenges result from the low position of documentation in the power structure. Documentation managers have less influence over schedules than managers in other disciplines and often find themselves trying to fit ten pounds of potatoes in a five pound sack. This section focuses on how to deal with these challenges effectively.

Managing Technology looks at the realities of technology for technical documentation. Technical documentation is often considered to be a non-technical discipline. In reality, not only do you need to deal with whatever technology is in your product or service, you need to deal with technologies that support your work. XML, Content Management Systems, and the Internet are all things you need to be concerned with, and you cannot expect much help from managers or engineers in other disciplines. The tools your team uses are distinct from those used in other disciplines. Understanding the possibilities and limitations is critical to your success. This section looks at how you can live with technology and acquire new technology. It also discusses technologies that support documentation, including XML, Content Management Systems, and the Internet.

3. Acknowledgements

Many people have helped make this book what it is. Thanks to everyone who read and commented on sections of this book through my blog, including: Jim Earley, Chip Gettinger, Judy Horton, Scott Hudson, Jim Leth, Mark Modig, Mike Ruscio, and Kate Shorey. Special thanks to Steve Bourgault, Jim Hamilton, Laura Praderio-Lynn, Larry Rowland, and Spence Wilcox for reading and commenting on large portions of this book.

Thanks to Garrett Long, who was largely responsible for convincing me to take my first job as a documentation manager. Thanks to Steve Bourgault, Bill Klinger, Sue Picus, and Ray Terry, who managed me during my time as a documentation manager; I learned a lot from each of you.

Thanks to John Hedtke for his wise counsel on writing and marketing, and to Scott Abel, the “Content Wrangler,” who helped in many ways. Thanks to the DocBook community, especially Norm Walsh and Bob Stayton, for keeping the DocBook flame alive and providing many of the tools used to write this book.

Finally, thanks to my wife Mei-li, who supported me in every way possible while I wrote this book.

Part I. Getting Started

What it takes
to start the
journey.

Chapter 1. Introduction

There they go.
I must run and catch up with them,
because I am their leader!

— Mahatma Gandhi

After 10 years developing software, including a few years leading a team informally, I felt ready to become a project manager. I had been a successful software developer, writing system and user software, and had recently returned from an assignment in Japan where I initiated and led a large project for a major customer in China. In my not so humble opinion, I was prepared to lead a crack development team to greater glory.

The day my opportunity arrived, I was called in to meet the Lab Manager. This was back when managers actually played the part. He wore a Brooks Brothers dark grey pin-stripe suit with a red “power” tie. His window office had an immaculate mahogany desk with a beautiful Newton's cradle and a couple of other high end executive toys. The only papers on his desk were neatly lined up in mahogany In/Out trays. He managed several hundred engineers and was responsible for millions of dollars in projects.

He told me that he wanted to “explore the possibility” of offering me a job managing technical documentation for the UNIX operating system. Managing technical documentation was far from my first choice, but the offer was not a complete surprise. The last two people to be promoted into management were first put in a documentation management job, then within a few months were given a lateral move to manage a software development team. It was commonly accepted that a promotion to documentation manager was a relatively safe way to let a manager get his or her feet wet; after all, how much trouble can you get into managing documentation?

This time, however, he wanted to stop the revolving door. He said he would only offer the job to someone who agreed not to seek another management position for at least two years. Had there been other openings, I never would have considered this job. My experience with documentation was sketchy at best. In fact, I barely recognized documentation as part of the process, let alone an essential part. But, there were no other openings, and it did not look like there would be any for quite a while, so I took the job.

That was nearly 20 years ago, and except for a couple of a short time outs, I have been managing technical documentation ever since. I have had the chance to do other things, but I keep drifting back to this field. I have found that managing technical documentation is both a challenge and great fun. Plus, I have had the opportunity to work with a group of interesting and talented individuals, who have taught me a lot.

By necessity, any individual's approach is constrained by his or her personal experience. While I have done my best to draw on the knowledge of others in the field, my approach reflects my skills and experience. My university training is in computer science and music, and I have continued to keep my technical skills up-to-date over the years, always having a software project or two and some music bubbling on the back burner.

My management experience is primarily in large companies, managing documentation for software products, some of them end-user products, some of them highly specialized system products, like the UNIX and Linux operating systems. In addition, I have managed several SGML/XML technology projects, including recent projects targeted at improved single-sourcing and content reuse using DocBook XML.

I believe the strongest management style is one that avoids tight control and encourages independence. I believe in light-weight processes, but thorough planning. I believe in treating writers like adult human beings, who nearly always know how to do their jobs better than I do. I believe in hiring the smartest and hardest working people I can find, and rewarding the...

Table of contents

• Managing Writers